파생 프로젝트 지원

일부 구성 변수를 사용하면 QDoc을 통해 Qt 기반 프로젝트를 지원할 수 있습니다. 이를 통해 프로젝트에 온라인 Qt 문서로의 링크를 포함시킬 수 있으며, 이는 QDoc이 별도의 명시적인 링크 명령 없이도 클래스 참조 문서로 연결되는 링크를 생성할 수 있음을 의미합니다.

설명

description 변수는 관련 프로젝트에 대한 간략한 설명을 저장합니다.

‘project’ 항목도 참조하십시오.

인덱스

indexes 변수는 로드할 인덱스 파일의 경로 집합을 정의합니다.

indexes = \
    $QT_INSTALL_DOCS/qtcore/qtcore.index \
    $SOME_OTHER_PROJECT/doc/foo.index

indexes 변수는 프로젝트의 종속성을 정의하는 데 있어 depends의 대안 역할을 합니다. 직접 경로가 제공되므로 QDoc을 호출할 때 --indexdir 명령줄 옵션을 사용할 필요가 없습니다.

두 변수 중 어느 것을 사용하든 종속성을 정의할 수 있습니다. Qt 문서에서는 depends 변수만을 사용합니다.

'depends', 'project', 'url' 항목도 참조하십시오.

예비

preliminary 변수를 사용하여 \preliminary 명령을 사용하여 요소에 할당된 상태 설명자를 사용자 정의할 수 있습니다.

기본적으로 QDoc은 API 참조에서 이러한 요소에 ` Preliminary ` 설명자를 지정하고, 메시지를 생성합니다.

"이 <요소 유형>은 개발 중이며 변경될 수 있습니다."

QDoc은 위 메시지의 <element type> 을 해당 유형(예: "module", "function" 또는 "class")으로 대체합니다.

사용자 정의 상태 설명자를 사용하려면 preliminary 변수를 정의하십시오:

preliminary = "Technology preview"

사용자 정의 상태 메시지를 사용하려면 preliminary.description 하위 변수도 정의하십시오:

preliminary = "Technology preview"
preliminary.description = "This \1 is in technology preview and is subject to change."

설명에 \1 자리 표시자가 나타나면, QDoc은 이를 요소 유형으로 대체합니다.

preliminary 변수는 Qt 6.12에서 QDoc에 도입되었습니다.

productname

문서화 대상 제품의 이름이 문서 이름과 다른 경우 productname 변수를 사용하십시오 project 이는 여러 문서 프로젝트 및/또는 모듈로 구성된 대규모 문서 세트의 경우 특히 유용합니다. 이를 통해 QDoc은 \since 명령어와 같은 특정 상황에서 프로젝트 이름 대신 제품 이름을 생성할 수 있기 때문입니다.

예를 들어, Qt는 Qt를 productname 로 정의하는 반면, 각 개별 모듈은 자체적인 project 이름을 정의합니다. 이를 통해 작성자는 \since 명령어에 대한 약어 표기법을 사용할 수 있게 해줍니다.

이 구성 변수는 Qt 6.9부터 QDoc에 도입되었습니다.

참조: \since.

프로젝트

project 변수는 .qdocconf 파일과 연관된 프로젝트의 이름을 지정합니다. 이 변수는 모든 프로젝트에서 반드시 설정해야 하는 필수 변수입니다.

프로젝트 이름은 해당 프로젝트의 인덱스 파일 이름을 구성하는 데 사용됩니다.

project = QtCreator

이렇게 하면 qtcreator.index 이라는 이름의 인덱스 파일이 생성됩니다.

프로젝트 이름에 공백이나 특수 문자가 포함된 경우, 생성된 인덱스 파일 이름에서는 해당 문자가 대시('-')로 대체됩니다.

‘depends’, ‘indexes’ 및 ‘description’ 항목도 참조하십시오.

projectroot

projectroot 변수는 경고 로그에서 상대 경로를 계산할 때 사용할 프로젝트 루트 디렉터리를 설정합니다.

projectroot = /path/to/project/root

QDoc은 다음 우선순위 순서에 따라 프로젝트 루트를 결정합니다:

1. QDOC_PROJECT_ROOT 환경 변수
2. projectroot 구성 변수
3. 둘 다 설정되어 있지 않은 경우, 절대 경로가 사용됩니다

프로젝트 루트가 설정된 경우, QDoc은 경고 로그 파일에서 절대 파일 경로를 상대 경로로 변환합니다. 이를 통해 서로 다른 빌드 환경 간에도 로그를 호환할 수 있게 됩니다.

Qt의 빌드 시스템은 ` QDOC_PROJECT_ROOT`을 자동으로 설정하므로, 일반적으로 ` projectroot `을 수동으로 설정할 필요가 없습니다.

QDoc을 독립형으로 사용할 경우, projectroot 를 설정하면 경고 로그의 이식성을 확보할 수 있습니다:

projectroot = /home/user/myproject
logwarnings = true

projectroot 변수는 QDoc 6.11에서 도입되었습니다. logwarnings 항목도 참조하십시오.

url

url 변수는 현재 프로젝트와 관련된 문서의 기본 URL을 저장합니다.

이 URL은 프로젝트에 대해 생성된 인덱스 파일에 저장됩니다. 인덱스 파일을 단독으로 사용할 경우, QDoc은 인덱스에 나열된 클래스, 함수 및 기타 항목에 대한 링크를 생성할 때 이 URL을 기본 URL로 사용합니다.

project     = QtCore
description = Qt Core Reference Documentation
url         = https://doc.qt.io/qt/

...

이를 통해 QDoc이 Qt Core 모듈 내의 엔티티에 대한 참조를 생성할 때마다 기본 URL이 https://doc.qt.io/qt/ 이 되도록 보장합니다.

‘depends’, ‘indexes ’ 및 ‘url.examples’ 항목도 참조하십시오.

url.examples

url.examples 변수는 현재 프로젝트와 관련된 예제의 기본 URL을 저장합니다.

이 변수가 정의되어 있으면, 각 예제 문서 페이지 하단에 예제 프로젝트 디렉터리로 연결되는 링크가 생성됩니다. url.examples 변수는 이 프로젝트와 관련된 예제의 루트 디렉터리를 가리키며, 온라인 저장소( http:// 또는 https://로 시작하는)나 로컬 파일 시스템(file://)으로 연결되는 링크일 수 있습니다.

url.examples 가 정의되지 않은 경우, QDoc은 대신 예제 파일 및 이미지 목록을 출력합니다.

예를 들어, 다음과 같은 정의가 주어졌을 때:

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/"
examplesinstallpath = corelib

이 경우, 다음 \example 명령어:

/*!
    \example threads/semaphores
    ...
*/

QDoc은 https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores 로 연결되는 링크를 생성합니다.

URL에 예시 경로 뒤에 추가 구성 요소(예: 쿼리 문자열)가 포함된 경우, \1 을 경로의 자리 표시자로 사용할 수 있습니다:

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/\1?h=$QT_VER"
examplesinstallpath = corelib

위와 동일한 \example 명령을 사용하고, $QT_VER 가 5.13 로 확장된다고 가정하면, 생성된 URL은 https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores?h=5.13 입니다.

url.examples 이 변수는 QDoc 버전 5.13에서 도입되었습니다.

url, examplesinstallpath 및 \example.

url.sources

url.sources 변수는 현재 프로젝트와 관련된 C++ 소스 코드의 기본 URL을 저장합니다. 이 URL은 github.com과 같은 저장소에서 프로젝트의 소스 코드를 확인하기 위한 것입니다.

url.sources.enabled 을 true 으로 설정하여 소스 링크를 활성화하십시오. 활성화되면 QDoc은 문서화된 각 C++ 엔티티의 ‘상세 설명’ 섹션에 있는 개요 (시그니처) 내에 선언으로 연결되는 링크를 생성합니다.

또한, url.sources.rootdir 을 통해 소스 파일의 루트 디렉터리를 정의하십시오. 생성된 링크는 기본 URL(url.sources)과 url.sources.rootdir 을 기준으로 한 소스 파일의 경로로 구성됩니다.

URL에 경로 뒤에 추가 구성 요소(예: 분기를 지정하는 쿼리 문자열)가 포함된 경우, \1 는 경로의 자리 표시자 역할을 합니다. 마찬가지로, \2 는 줄 번호의 자리 표시자 역할을 합니다.

url.sources.linktext 소스 링크에 대해 사용자에게 표시될 링크 텍스트를 설정합니다. 기본적으로 링크 텍스트는 빈 문자열입니다. HTML 출력에서 링크의 스타일을 지정하려면 a.srclink CSS 선택자를 사용하십시오.

예를 들어, qtbase/src/gui/doc/qtgui.qdocconf 에 다음과 같은 구성을 지정하면:

url.sources = "https://code.qt.io/cgit/qt/qtbase.git/tree/\1?h=$QT_VER#n\2"
url.sources.rootdir = ../../..    # root of the `qtbase` repository
url.sources.linktext = "(source)"
url.sources.enabled = true

QDoc은 QT_VER 환경 변수로 정의된 브랜치에 따라, 문서화된 각 C++ 엔티티에 대해 code.qt.io로 연결되는 링크를 생성합니다.

url.sources 변수는 Qt 6.10부터 QDoc에 도입되었습니다.

usealttextastitle

경우에 따라 그래픽 브라우저에서 이미지가 렌더링될 때 “도구 설명”을 표시하는 것이 바람직할 수 있습니다. QDoc은 이를 구현할 수 있는 방법을 제공하며, 이때 \image 명령에 선택적으로 문자열로 지정된 대체 텍스트가 이미지의 title 속성으로도 사용됩니다. QDoc 구성 파일에서 이 변수를 usealttextastitle = true 으로 설정하여 이 동작을 활성화하십시오.

이 구성 변수는 Qt 6.9부터 QDoc에 도입되었습니다.

파생 프로젝트 지원 방법

이 기능은 QDoc이 Qt 참조 문서를 생성할 때 생성하는 포괄적인 색인을 활용합니다.

예를 들어, qtgui.qdocconf ( Qt GUI 의 구성 파일)에는 다음과 같은 변수 정의가 포함되어 있습니다:

project     = QtGui
description = Qt GUI Reference Documentation
url         = https://doc.qt.io/qt/

...

프로젝트 변수 이름은 색인 파일의 이름을 구성하는 데 사용되며, 이 경우 qtgui.index 파일이 생성됩니다. URL은 색인 파일에 저장됩니다. 이후 QDoc은 색인에 나열된 클래스, 함수 및 기타 항목에 대한 링크를 생성할 때 이를 기본 URL로 사용합니다.

‘depends’, ‘indexes’, ‘project’, ‘url’ 항목도 참조하십시오.