일반 구성 변수

일반 QDoc 구성 변수를 사용하여 QDoc이 문서를 생성하는 데 필요한 다양한 소스 파일을 찾을 위치와 생성된 문서를 저장할 디렉터리를 정의할 수 있습니다. 또한 QDoc 자체를 약간 조작하여 출력 및 처리 동작을 제어할 수도 있습니다.

코드 들여쓰기

codeindent 변수는 코드 스니펫을 작성할 때 QDoc이 사용하는 들여쓰기 수준을 지정합니다.

QDoc은 원래 코드 조각을 주변 텍스트와 쉽게 구분할 수 있도록 코드 들여쓰기에 4칸의 하드코딩된 값을 사용했습니다. 스타일시트를 사용하여 특정 유형의 HTML 요소의 모양을 조정할 수 있으므로 이 수준의 들여쓰기가 항상 필요한 것은 아닙니다.

코드 접두사, 코드 접미사

codeprefix 및 codesuffix 변수는 각 코드 조각을 묶는 문자열 쌍을 지정합니다.

정의

defines 변수는 QDoc이 인식하고 응답할 C++ 전처리기 심볼을 지정합니다.

defines 변수를 사용하여 전처리기 심볼을 지정하는 경우 \if 명령을 사용하여 전처리기 심볼이 정의된 경우에만 포함되는 문서를 묶을 수도 있습니다.

defines = QT_GUI_LIB

이렇게 하면 QDoc에서 이러한 기호를 정의해야 하는 코드를 처리할 수 있습니다. 예를 들어

#ifdef Q_GUI_LIB
void keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay = -1)
#endif

명령줄에서 -D 옵션을 사용하여 전처리기 기호를 수동으로 정의할 수도 있습니다. 예를 들어

currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf

이 경우 -D 옵션은 QDoc이 qtgui.qdocconf 파일에 정의된 소스 파일을 처리할 때 qtforpython 전처리기 기호를 정의하도록 합니다.

거짓 및 \if도 참조하십시오.

depends

depends 변수는 이 프로젝트가 유형 상속을 위한 링크 대상 및 문서가 링크해야 하는 다른 모든 것을 확인하기 위해 의존하는 다른 문서 프로젝트의 목록을 정의합니다.

Qt 자체와 마찬가지로, Qt에 대한 문서는 여러 모듈에 분산되어 있습니다. 다중 모듈 문서 프로젝트에서 단일 모듈에 대한 최소 종속성 세트는 실제 빌드 종속성으로 구성됩니다. 또한 전체 문서 세트의 최상위 진입점 역할을 하고 탐색 링크를 제공하는 문서 프로젝트(모듈)가 있는 경우 각 모듈 문서는 이를 종속성으로 포함해야 합니다.

QDoc이 프로젝트에 대한 문서를 생성할 때 프로젝트의 각 링크 가능한 엔티티에 대한 URL이 포함된 .index 파일도 생성합니다. 각 종속성은 프로젝트의 (소문자) 이름입니다. 이 이름은 해당 프로젝트에 대해 생성된 인덱스 파일의 기본 이름과 일치해야 합니다.

depends = \
    qtdoc \
    qtcore \
    qtquick

종속성이 있고 depends 변수를 사용하는 프로젝트에서 QDoc을 호출할 때 하나 이상의 -indexdir 경로를 명령줄 옵션으로 전달해야 합니다. QDoc은 이러한 경로를 사용하여 종속 요소의 인덱스 파일을 검색합니다.

qdoc mydoc.qdocconf -outputdir $PWD/html -indexdir $QT_INSTALL_DOCS

위와 같이 QDoc은 qtdoc 에 대한 종속성에 대해 $QT_INSTALL_DOCS/qtdoc/qtdoc.index 파일을 검색합니다. 종속성에 대한 인덱스 파일을 찾을 수 없는 경우 QDoc은 경고를 출력합니다.

depends 명령은 '*'라는 특수 값도 허용합니다. 이 값은 지정된 인덱스 디렉터리에서 찾은 모든 인덱스 파일, 즉 "모든 것에 의존"하는 인덱스 파일을 로드하도록 QDoc에 지시합니다.

depends = *

인덱스, 프로젝트 및 URL도 참조하세요.

예제

exampledirs 변수는 예제 파일의 소스 코드가 포함된 디렉터리를 지정합니다.

examples 및 exampledirs 변수는 \quotefromfile, \quotefile 및 \example 명령에서 사용됩니다. examples 및 exampledirs 변수가 모두 정의되어 있으면 QDoc은 두 변수 모두에서 먼저 examples를 검색한 다음 exampledirs를 검색합니다.

QDoc은 지정된 순서대로 디렉터리를 검색하고 가장 먼저 찾은 일치하는 파일을 받아들입니다. 하위 디렉터리가 아닌 지정된 디렉터리에서만 검색합니다.

exampledirs = $QTDIR/doc/src \
              $QTDIR/examples \
              $QTDIR \
              $QTDIR/qmake/examples

examples    = $QTDIR/examples/widgets/analogclock/analogclock.cpp

처리할 때

\quotefromfile widgets/calculator/calculator.cpp

QDoc은 calculator.cpp 이라는 파일이 값으로 나열되어 있는지 확인합니다. examples 변수에 값이 있는지 확인합니다. 없는 경우 exampledirs 변수를 검색하여 먼저 다음과 같은 파일이 있는지 확인합니다.

$QTDIR/doc/src/widgets/calculator/calculator.cpp

파일이 없는 경우, QDoc은 계속해서

$QTDIR/examples/widgets/calculator/calculator.cpp

등의 파일을 계속 찾습니다.

예시를 참조하세요.

예제

examples 변수를 사용하면 지정한 디렉터리에 있는 파일 외에 개별 예제 파일을 exampledirs 변수로 지정할 수 있습니다.

examples 및 exampledirs 변수는 \quotefromfile, \quotefile 및 \example 명령에 사용됩니다. examples 및 exampledirs 변수가 모두 정의되어 있으면 QDoc은 두 변수 모두에서 검색하며, 먼저 examples 에서 검색한 다음 exampledirs.

QDoc은 examples 변수에 대해 나열된 값을 지정된 순서대로 검색하고 가장 먼저 찾은 값을 받아들입니다.

자세한 예는 exampledirs 명령을 참조하세요. 하지만 파일이 examples 변수에 나열되어 있다는 것을 알고 있는 경우에는 경로를 지정할 필요가 없습니다:

\quotefromfile calculator.cpp

exampledirs를 참조하세요.

examplesinstallpath

examplesinstallpath 변수는 설치된 예제 디렉터리 아래에 이 프로젝트의 예제 루트 경로를 설정합니다.

모든 예제의 루트 설치 경로가 QT_INSTALL_EXAMPLES 라고 가정하면, 예제의 경로

<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>

는 이 문서 프로젝트 내에서 단일 예제의 경로를 참조하는 데 사용됩니다. 이러한 경로는 예제 매니페스트 파일에 기록되며 Qt Creator 에서 읽습니다.

올바른 경로를 확인하려면 examplesinstallpath 이 exampledirs에 나열된 디렉터리 중 하나와 일치해야 합니다. 각 \example 명령의 인수로 전달되는 경로는 exampledirs의 경로에 상대적입니다.

예를 들어

exampledirs = ./snippets \
              ../../../examples/mymodule

examplesinstallpath = mymodule

다음과 같은 \example 명령이 주어집니다:

/*!
    \example basic/hello
    ...
*/

그러면 이 예제의 매니페스트 파일에 mymodule/basic/hello 경로가 기록됩니다.

참고: exampledirs, \example 및 \meta.

examples.fileextensions

examples.fileextensions 변수는 문서에 표시할 예제 파일을 수집할 때 QDoc이 찾을 파일 확장명을 지정합니다.

기본 확장자는 *.cpp, *.h, *.js, *.xq, *.svg, *.xml 및 *.ui입니다.

확장자는 표준 와일드카드 표현식으로 제공됩니다. '+='를 사용하여 필터에 파일 확장자를 추가할 수 있습니다. 예를 들어

examples.fileextensions += *.qrc

headers.fileextensions도 참조하세요.

제외된

excludedirs 변수는 동일한 디렉터리가 sourcedirs 또는 headerdirs 변수에 포함되어 있더라도 QDoc에서 처리해서는 안 되는 디렉터리를 나열하는 데 사용됩니다.

예를 들어

sourcedirs =  src/corelib
excludedirs = src/corelib/tmp

이 옵션을 실행하면 QDoc은 나열된 디렉터리를 추가 고려 대상에서 제외합니다. 이러한 디렉터리에 있는 파일은 QDoc에서 읽지 않습니다.

제외 파일도 참조하세요.

제외 파일

excludefiles 변수를 사용하면 QDoc에서 처리하지 말아야 할 개별 파일을 지정할 수 있습니다.

excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
                $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp

qtbase용 qdocconf 파일에 위의 내용을 포함하면 QWidget 에 대한 클래스 문서가 생성되지 않습니다.

Qt 5.6부터는 간단한 와일드카드('*' 및 '?')도 excludefiles 에서 인식합니다. 예를 들어, 모든 개인 Qt 헤더 파일을 구문 분석에서 제외하려면 다음을 정의합니다:

excludefiles += "*_p.h"

excludedirs도 참조하십시오.

extraimages

extraimages 변수는 생성된 문서에 특정 이미지를 포함하도록 QDoc에 지시합니다.

이미지 파일이 imagedirs에서 참조되는 경우 QDoc은 자동으로 이미지 파일을 \image 또는 \inlineimage 명령에 의해 참조되는 경우. 추가 이미지를 복사하려면 extraimages 변수를 사용하여 이미지를 지정해야 합니다.

일반적인 구문은 format.extraimages = image.

상황에 맞는 예는 HTML.postheader 변수에 대한 설명을 참조하세요.

예시:

HTML.extraimages = images/qt-logo.png

이미지 및 이미지도 참조하세요.

허위 사실

falsehoods 변수는 지정된 전처리기호의 진리 값을 거짓으로 정의합니다.

변수 값은 정규 표현식입니다(자세한 내용은 QRegularExpression 참조). 전처리기 기호에 대해 이 변수가 설정되지 않은 경우 QDoc은 해당 진리 값이 참이라고 가정합니다. 예외는 항상 거짓인 '0'입니다.

QDoc은 다음과 같은 전처리기 구문을 인식하고 평가할 수 있습니다:

#ifdef NOTYET
 ...
#endif

#if defined (NOTYET)
 ...
#end if

그러나 다음과 같은 알 수 없는 구문에 직면하면

#if NOTYET
    ...
#endif

falsehoods 변수 항목 내에 전처리기 기호가 지정되지 않는 한 QDoc은 기본적으로 참으로 평가합니다:

falsehoods = NOTYET

정의도 참조하세요.

생성색인

generateindex 변수에는 HTML 문서 생성 시 색인 파일을 생성할지 여부를 지정하는 부울 값이 포함되어 있습니다.

기본적으로 인덱스 파일은 항상 HTML 문서와 함께 생성되므로 이 변수는 일반적으로 이 기능을 비활성화하거나(값을 false)로 설정하거나(값을 true)로 설정하여 WebXML 출력에 대한 인덱스 생성을 활성화할 때만 사용됩니다.

headerdirs

headerdirs 변수는 문서에 사용된 .cpp 소스 파일과 관련된 헤더 파일이 포함된 디렉터리를 지정합니다.

headerdirs = $QTDIR/src \
             $QTDIR/extensions/activeqt \
             $QTDIR/extensions/motif \
             $QTDIR/tools/designer/src/lib/extension \
             $QTDIR/tools/designer/src/lib/sdk \
             $QTDIR/tools/designer/src/lib/uilib

실행되면 QDoc이 가장 먼저 하는 일은 지정된 헤더를 읽는 것입니다. headers 변수에 지정된 헤더와 headerdir 변수에 지정된 디렉터리(모든 하위 디렉터리 포함)에 있는 헤더를 읽어 클래스 및 해당 함수의 내부 구조를 구축합니다.

그런 다음 변수에 지정된 소스와 sources에 지정된 소스와 sourcedirs 변수에 지정된 디렉토리(모든 하위 디렉토리 포함)에 있는 소스를 읽어서 헤더 파일에서 검색한 구조와 문서를 병합합니다.

headers 및 headerdirs 변수가 모두 정의된 경우 QDoc은 먼저 두 변수를 모두 읽은 다음 headers 를 읽은 다음 headerdirs 를 읽습니다.

지정된 디렉터리에서 QDoc은 fileextensions 에 지정된 파일만 읽습니다. headers.fileextensions 변수에 지정된 파일만 읽습니다. 로 지정된 파일은 headers 로 지정된 파일은 파일 확장자를 고려하지 않고 읽습니다.

headers 및 headers.fileextensions도 참조하세요.

headers

headers 변수를 사용하면 지정된 디렉터리에 있는 파일 외에도 개별 헤더 파일을 지정할 수 있습니다. headerdirs 변수로 지정할 수 있습니다.

headers = $QTDIR/src/gui/widgets/qlineedit.h \
          $QTDIR/src/gui/widgets/qpushbutton.h

headers 변수를 처리할 때 QDoc은 다음과 같은 방식으로 작동합니다. headerdirs 변수를 처리할 때와 동일한 방식으로 작동합니다. 자세한 내용은 headerdirs 변수를 참조하세요.

headerdirs도 참조하세요.

headers.fileextensions

headers.fileextensions 변수는 헤더에 사용되는 확장자를 지정합니다.

변수에 지정된 헤더 파일을 처리할 때 headerdirs 변수에 지정된 헤더 파일을 처리할 때 QDoc은 headers.fileextensions 변수에 지정된 파일 확장자를 가진 파일만 읽습니다. 이렇게 하면 QDoc은 관련 없는 파일을 읽는 데 시간을 낭비하지 않습니다.

기본 확장자는 *.ch, *.h, *.h++, *.hh, *.hpp 및 *.hxx입니다.

확장자는 표준 와일드카드 표현식으로 제공됩니다. '+='를 사용하여 필터에 파일 확장자를 추가할 수 있습니다. 예를 들어

header.fileextensions += *.H

헤더 디렉터리도 참조하세요.

포함 경로

includepaths 변수는 문서 주석에 대한 C++ 코드를 구문 분석하는 데 사용하는 Clang 구문 분석기에 추가 포함 경로를 전달하는 데 사용됩니다.

이 변수에는 -I (포함 경로), -F (macOS 프레임워크 포함 경로) 또는 -isystem (시스템 포함 경로)가 접두사로 붙은 경로 목록이 허용됩니다. 접두사가 생략된 경우 기본적으로 -I 가 사용됩니다.

현재 .qdocconf 파일에 상대적인 경로는 절대 경로로 확인됩니다. 파일 시스템에 존재하지 않는 경로는 무시됩니다.

모듈 헤더를 참조하십시오.

무시 단어

ignorewords 변수는 QDoc이 하이퍼링크 대상을 확인할 때 무시할 문자열 목록을 지정하는 데 사용됩니다.

QDoc에는 C++ 또는 QML 엔티티와 유사한 단어에 대해 링크가 시도되는 자동 링크 기능이 있습니다. 구체적으로, 문자열의 길이가 3자 이상이고 공백이 없으며 다음과 같은 경우 자동 연결이 가능합니다.

• 카멜케이스 단어, 즉 인덱스가 0보다 큰 대문자를 하나 이상 포함하는 경우, 또는
• () 또는 :: 하위 문자열을 포함하거나
• 또는 @ 또는 _ 과 같은 특수 문자를 하나 이상 포함합니다.

ignorewords 에 정규화된 단어를 추가하면 QDoc이 해당 단어를 자동으로 연결하지 않습니다. 예를 들어 OpenGL이라는 단어가 유효한 링크 대상(섹션, \페이지 또는 \외부 페이지 제목)인 경우 각 단어에 대한 하이퍼링크는 다음을 사용하여 피할 수 있습니다.

ignorewords += OpenGL

l로 명시적으로 연결하면 무시된 단어에 대해 계속 작동합니다.

ignorewords 변수는 QDoc 5.14에 도입되었습니다.

무시 이후

ignoresince 변수는 \since 명령에 전달된 버전에 대한 컷오프 값을 설정하는 데 사용됩니다. 컷오프보다 낮은 버전을 정의하는 모든 \since 명령은 무시되며 출력을 생성하지 않습니다.

컷오프 값은 프로젝트별로 다릅니다. 프로젝트 이름은 하위 변수로 정의할 수 있습니다. 기본 프로젝트 이름은 Qt입니다. 예를 들어

ignoresince      = 5.0
ignoresince.QDoc = 5.0

주요 버전이 4 이하이고 프로젝트가 QDoc 또는 정의되지 않은 경우 \since 명령은 무시됩니다.

\since 3.2          # Ignored
\since 5.2          # Documented (as 'Qt 5.2')
\since QDoc 4.6     # Ignored
\since QtQuick 2.5  # Documented

ignoresince 변수는 QDoc 5.15에 도입되었습니다.

이후를 참조하세요.

imagedirs

imagedirs 변수는 문서에 사용된 이미지가 포함된 디렉터리를 지정합니다.

그리고 images 및 imagedirs 변수는 \image 및 \inlineimage 명령에 사용됩니다. 와 변수가 모두 정의된 경우 images 및 imagedirs 변수가 모두 정의되어 있으면 QDoc은 두 변수 모두에서 검색합니다. 먼저 images에서 검색한 다음 imagedirs 에서 검색합니다.

QDoc은 지정된 순서대로 디렉터리를 검색하여 가장 먼저 일치하는 파일을 찾습니다. 하위 디렉터리가 아닌 지정된 디렉터리에서만 검색합니다.

imagedirs = $QTDIR/doc/src/images \
            $QTDIR/examples

images    = $QTDIR/doc/src/images/calculator-example.png

처리할 때

\image calculator-example.png

그런 다음 QDoc은 images 변수에 값으로 나열된 계산기 예제.png라는 파일이 있는지 확인합니다. 파일이 없으면 imagedirs 변수에서 검색합니다:

$QTDIR/doc/src/images/calculator-example.png

파일이 존재하지 않는 경우 QDoc은 다음과 같은 파일을 찾습니다.

$QTDIR/examples/calculator-example.png

language

language 변수는 문서에 사용되는 소스 코드의 언어를 지정합니다. 특히, 이 변수는 \code ... \endcode 블록 내에서 소스 코드를 구문 분석하는 기본 언어를 정의합니다.

language = Cpp

기본 언어는 C++(Cpp)이며, 명시적으로 지정할 필요는 없습니다. 문서의 코드 스니펫이 주로 QML 코드로 구성되어 있는 경우 QML을 기본값으로 설정하세요:

language = QML

code-command[\code}도 참조하세요.

위치정보

locationinfo 부울 변수는 각 엔티티에 대한 자세한 위치 정보를 .index-파일 및 .webxml-파일에 기록할지 여부를 결정합니다(WebXML 출력 형식을 사용하는 경우).

위치 정보는 소스 코드의 선언 또는 문서 주석 블록의 전체 경로와 줄 번호로 구성됩니다.

false 로 설정하면 위치 정보가 꺼집니다:

locationinfo = false

기본값은 true 입니다.

locationinfo 변수는 QDoc 5.15에 도입되었습니다.

macro

macro 변수는 자신만의 간단한 QDoc 명령을 만드는 데 사용됩니다. 구문은 macro.command = definition명령은 문자와 숫자 문자의 조합으로 제한되며 대시나 밑줄과 같은 특수 문자는 사용할 수 없습니다. 정의는 QDoc 구문을 사용하여 작성됩니다.

매크로 변수는 한 가지 유형의 출력 생성에만 사용하도록 제한할 수 있습니다. 예를 들어 매크로 이름에 .HTML 을 추가하면 매크로는 HTML 출력을 생성할 때만 사용됩니다.

macro.key              = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"

첫 번째 매크로는 굵은 글꼴을 사용하여 인수를 렌더링하는 \key 명령을 정의합니다. 두 번째 매크로는 위 첨자 별표를 렌더링하는 \raisedaster 명령을 정의하지만 HTML을 생성할 때만 해당됩니다.

매크로는 최대 7개의 매개변수를 사용할 수도 있습니다:

macro.hello            = "Hello \1!"

매개변수는 다른 명령과 동일한 방식으로 매크로에 전달됩니다:

\hello World

두 개 이상의 매개변수를 사용하거나 인수에 공백이 포함된 경우 각 인수를 중괄호로 묶어야 합니다:

macro.verinfo          = "\1 (version \2)"

\verinfo {QFooBar} {1.0 beta}

확장 매크로에 대한 추가 정규식 패턴 일치를 위해 특수 매크로 옵션인 match를 추가할 수 있습니다.

예를 들어

macro.qtminorversion       = "$QT_VER"
macro.qtminorversion.match = "\\d+\\.(\\d+)"

그러면 QT_VER 환경 변수를 기반으로 부 버전으로 확장되는 매크로 \qtminorversion이 생성됩니다.

일치 패턴을 정의하는 매크로는 모든 캡처 그룹(괄호)을 함께 연결하거나 패턴에 캡처 그룹이 포함되지 않은 경우 정확히 일치하는 문자열을 출력합니다.

사전 정의 매크로에 대한 자세한 내용은 매크로를 참조하세요.

매니페스트메타

manifestmeta 변수는 QDoc에서 생성된 예제 매니페스트 파일에 대한 추가 메타 콘텐츠를 지정합니다.

자세한 내용은 매니페스트 메타 콘텐츠 섹션을 참조하세요.

moduleheader

moduleheader 변수는 문서화된 C++ 모듈의 모듈 헤더 이름을 정의합니다.

C++ API를 문서화하는 프로젝트에는 모듈의 모든 공용 클래스, 네임스페이스 및 헤더 파일을 포함하는 모듈 수준 헤더가 필요합니다. QDoc의 Clang 구문 분석기는 이 파일을 사용하여 소스 파일 구문 분석 속도를 높이기 위해 모듈에 대한 사전 컴파일된 헤더(PCH)를 빌드합니다.

기본적으로 프로젝트 이름은 모듈 헤더 이름으로도 사용됩니다.

project = QtCore

위의 프로젝트 이름을 사용하면 QDoc은 먼저 명령줄 인수로 전달된 경로를 사용한 다음 포함 경로 변수에 나열된 경로를 사용하여 알려진 모든 포함 경로에서 모듈 헤더인 QtCore를 검색합니다.

모듈 헤더를 찾을 수 없는 경우 QDoc은 경고를 표시합니다. 그런 다음 headerdirs 변수에 나열된 헤더를 기반으로 인공 모듈 헤더를 빌드하려고 시도합니다.

Qt 문서 프로젝트의 경우, project 변수가 올바르게 설정되어 있다면 빌드 시스템은 일반적으로 모듈 헤더를 찾을 수 있는 올바른 포함 경로를 QDoc에 제공합니다. moduleheader 변수는 QDoc이 검색할 대체 파일 이름을 제공합니다.

프로젝트에 C++ 문서가 없는 경우 moduleheader 을 빈 문자열로 설정하여 PCH 생성을 건너뛰도록 QDoc에 지시해야 합니다:

# No C++ code to document in this project
moduleheader =

포함 경로 및 프로젝트도 참조하세요.

자연 언어

naturallanguage 변수는 QDoc에서 생성된 문서에 사용되는 자연어를 지정합니다.

naturallanguage = zh-Hans

기본적으로 자연어는 레거시 문서와의 호환성을 위해 en 입니다.

QDoc은 lang 및 xml:lang 속성을 사용하여 생성하는 HTML에 자연어 정보를 추가합니다.

소스 인코딩, 출력 인코딩, C.7도 참조하세요 . lang 및 xml:lang 속성 및 모범 사례 13: Hans 및 Hant 코드 사용하기를 참조하세요.

탐색

navigation 하위 변수가 정의되어 있으면 각 페이지에 대해 생성된 탐색 모음에 표시되는 홈페이지, 랜딩 페이지, C++ 클래스 페이지 및 QML 유형 페이지를 설정합니다.

여러 하위 프로젝트(예: Qt 모듈)가 있는 프로젝트에서 각 하위 프로젝트는 일반적으로 자체 랜딩 페이지를 정의하지만 모든 하위 프로젝트에서 동일한 홈 페이지가 사용됩니다.

하위 변수

예를 들어:

# Common configuration
navigation.homepage  = index.html
navigation.hometitle = "Qt $QT_VER"

# qtquick.qdocconf
navigation.landingpage    = "Qt Quick"
navigation.cppclassespage = "Qt Quick C++ Classes"
navigation.qmltypespage   = "Qt Quick QML Types"

위의 구성은 Item QML 유형에 대해 다음과 같은 탐색 모음을 생성합니다:

Qt 5.10 > Qt Quick > QML Types > Item QML Type

outputdir

outputdir 변수는 QDoc이 생성된 문서를 저장할 디렉터리를 지정합니다.

outputdir = $QTDIR/doc/html

는 생성된 Qt 참조 문서를 $QTDIR/doc/html에 찾습니다. 예를 들어, QWidget 클래스에 대한 설명서는

$QTDIR/doc/html/qwidget.html

관련 이미지는 images 하위 디렉터리에 저장됩니다.

출력 인코딩

outputencoding 변수는 QDoc에서 생성된 문서에 사용되는 인코딩을 지정합니다.

outputencoding = UTF-8

기본적으로 출력 인코딩은 레거시 문서와의 호환성을 위해 ISO-8859-1 (Latin1)입니다. 일부 언어, 특히 비유럽 언어에 대한 문서를 생성할 때는 이것만으로는 충분하지 않으며 UTF-8과 같은 인코딩이 필요합니다.

QDoc은 이 인코딩을 사용하여 HTML을 인코딩하고 브라우저에 사용 중인 인코딩을 나타내는 올바른 선언을 생성합니다. 또한 브라우저에 완전한 문자 인코딩 및 언어 정보 세트를 제공하려면 naturallanguage 구성 변수를 지정해야 합니다.

출력 인코딩 및 naturallanguage도 참조하세요.

outputformats

outputformats 변수는 생성된 문서의 형식을 지정합니다.

Qt 5.11부터 QDoc은 HTML과 WebXML 형식을 지원하며, Qt 5.15부터는 DocBook으로도 문서를 생성할 수 있습니다. outputformats 을 지정하지 않으면 QDoc은 기본 형식인 HTML로 문서를 생성합니다. 전용 출력 디렉토리 및 기타 설정과 함께 모든 출력 형식을 지정할 수 있습니다. 예를 들어

outputformats = WebXML HTML
WebXML.nosubdirs = true
WebXML.outputsubdir = webxml
WebXML.quotinginformation = true

이렇게 하면 기본 설정을 사용하여 HTML 문서를 생성하고 출력 하위 디렉터리 webxml에 WebXML 문서를 생성합니다.

출력 접두사

outputprefixes 변수는 파일 유형과 생성된 문서에서 출력 파일 이름 앞에 추가할 접두사 간의 매핑을 지정합니다.

QDoc은 QML 유형, C++ 클래스, 네임스페이스 및 헤더 파일 참조 페이지의 파일 이름에 출력 접두사를 추가하는 기능을 지원합니다.

outputprefixes     = QML CPP
outputprefixes.QML = uicomponents-
outputprefixes.CPP = components-

기본적으로 QML 유형에 대한 API 설명서가 포함된 파일의 접두사는 qml- 입니다. 위의 예에서는 uicomponents- 접두사가 대신 사용됩니다.

마찬가지로 C++ 유형 문서 페이지의 접두사는 위 예제에서 components- 입니다. 기본적으로 C++ 유형 페이지에는 접두사가 없습니다.

출력 접두사

outputsuffixes 변수는 출력 파일 이름에 표시되는 모듈 또는 유형 이름에 적용할 파일 유형과 접미사 간의 매핑을 지정합니다.

QDoc은 모듈 페이지, QML 유형, C++ 클래스, 네임스페이스 및 헤더 파일 참조 페이지의 파일 이름에 출력 접미사를 추가하는 것을 지원합니다.

기본적으로 접미사는 사용되지 않습니다. QML 출력 접미사를 정의하면 QML 유형 및 QML 모듈 페이지의 파일 이름에 표시되는 모듈 이름에 접미사로 적용됩니다.

C++ 유형의 파일 이름에는 모듈 이름이 포함되지 않습니다. CPP 출력 접미사가 정의되어 있으면 유형 이름에 접미사로 적용됩니다.

outputsuffixes = QML CPP
{outputsuffixes.QML,outputsuffixes.CPP} = -tp

위의 정의에 따라 QML 모듈 이름 FooBar와 기본 출력 접두사 (qml-)가 주어지면 QML 유형 FooWidget에 대해 생성된 파일의 이름은 qml-foobar-tp-foowidget.html 입니다.

마찬가지로, C++ 클래스 QFoobar의 경우 QDoc은 qfoobar-tp.html 을 생성합니다.

outputsuffixes 변수는 QDoc 5.6에 도입되었습니다.

qhp

qhp 하위 변수는 Qt Help 프로젝트 (qhp) 파일에 기록할 정보를 정의하는 데 사용됩니다.

이 프로세스에 대한 자세한 내용은 도움말 프로젝트 파일 만들기 장을 참조하세요.

QDoc 6.6부터 기본 qhp 변수를 true 으로 설정하면 유효한 도움말 프로젝트 구성이 예상됩니다:

qhp = true

그런 다음 프로젝트 구성이 qhp.projects 을 정의하지 않은 경우 QDoc은 경고를 발행합니다. 이 기능은 최상위 .qdocconf 파일을 공유하는 모든 문서 프로젝트(Qt에서와 같이)가 올바르게 구성되었는지 확인하는 데 유용합니다.

경고를 끄려면 변수를 false 로 설정합니다.

소스

sourcedirs 변수는 문서에 사용된 .cpp 또는 .qdoc 파일이 포함된 디렉터리를 지정합니다.

sourcedirs  += .. \
               ../../../examples/gui/doc/src

실행되면 QDoc이 가장 먼저 하는 일은 지정된 헤더를 읽는 것입니다. header 변수에 지정된 헤더와 headerdir 변수에 지정된 디렉터리(모든 하위 디렉터리 포함)에 있는 헤더를 읽어 클래스 및 해당 함수의 내부 구조를 구축합니다.

그런 다음 변수에 지정된 헤더와 sources변수에 지정된 소스와 sourcedirs 변수에 지정된 디렉토리(모든 하위 디렉토리 포함)에 있는 소스를 읽어서 헤더 파일에서 검색한 구조와 문서를 병합합니다.

sources 및 sourcedirs 변수가 모두 정의된 경우 QDoc은 먼저 두 변수를 모두 읽습니다. sources 다음 sourcedirs.

지정된 디렉터리에서 QDoc은 fileextensions 에 지정된 파일만 읽습니다. sources.fileextensions 변수에 지정된 파일만 읽습니다. 로 지정된 파일은 sources 로 지정된 파일은 파일 확장자에 관계없이 읽습니다.

소스 및 sources.fileextensions도 참조하세요.

소스 인코딩

sourceencoding 변수는 소스 코드 및 문서에 사용되는 인코딩을 지정합니다.

sourceencoding = UTF-8

기본적으로 소스 인코딩은 레거시 문서와의 호환성을 위해 ISO-8859-1 (Latin1)입니다. 일부 언어, 특히 비유럽 언어의 경우 이것만으로는 충분하지 않으며 UTF-8과 같은 인코딩이 필요합니다.

QDoc은 인코딩을 사용하여 소스 및 문서 파일을 읽지만, C++ 컴파일러의 제한으로 인해 소스 코드 주석에 ASCII 이외의 문자를 사용하지 못할 수도 있습니다. 이러한 경우 문서 파일에 API 문서를 완전히 작성할 수 있습니다.

자연어 및 출력 인코딩도 참조하세요.

소스

sources 변수를 사용하면 sourcedirs 변수로 지정한 디렉터리에 있는 파일 외에 개별 소스 파일을 지정할 수 있습니다.

sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
          $QTDIR/src/gui/widgets/qpushbutton.cpp

sources 변수를 처리할 때 QDoc은 sourcedirs 변수를 처리할 때와 동일한 방식으로 작동합니다. 자세한 내용은 sourcedirs 변수를 참조하세요.

sourcedirs도 참조하세요.

sources.fileextensions

sources.fileextensions 변수는 소스 디렉터리 내의 파일을 필터링합니다.

변수에 지정된 소스 파일을 처리할 때 sourcedirs 변수에 지정된 소스 파일을 처리할 때 QDoc은 sources.fileextensions 변수에 지정된 파일 확장자를 가진 파일만 읽습니다. 이러한 방식으로 QDoc은 관련 없는 파일을 읽는 데 시간을 낭비하지 않습니다.

기본 확장자는 *.c++, *.cc, *.cpp, *.cxx, *.mm, *.qml 및 *.qdoc입니다.

확장자는 표준 와일드카드 표현식으로 제공됩니다. '+='를 사용하여 필터에 파일 확장자를 추가할 수 있습니다. 예를 들어

sources.fileextensions += *.CC

출처 및 소스도 참조하세요.

가짜

spurious 변수는 지정된 QDoc 경고를 출력에서 제외합니다. 경고는 표준 와일드카드 표현식을 사용하여 지정됩니다.

spurious = "Cannot find .*" \
"Missing .*"

는 이러한 표현식 중 하나와 일치하는 경고가 QDoc 실행 시 출력에 포함되지 않도록 합니다. 예를 들어 다음 경고는 출력에서 생략됩니다:

src/opengl/qgl_mac.cpp:156: Missing parameter name

구문 강조

syntaxhighlighting 변수는 생성하는 문서에서 인용된 소스 코드에 구문 강조 표시를 수행할지 여부를 지정합니다.

syntaxhighlighting = true

로 설정하면 지원되는 모든 프로그래밍 언어에 대해 구문 강조 표시가 활성화됩니다.

tabsize

tabsize 변수는 탭 문자의 크기를 정의합니다.

tabsize = 4

는 탭 문자의 크기를 공백 4칸으로 지정합니다. 변수의 기본값은 8이며 지정할 필요가 없습니다.

태그 파일

tagfile 변수는 HTML이 생성될 때 작성할 Doxygen 태그 파일을 지정합니다.

version

version 변수는 문서화된 소프트웨어의 버전 번호를 지정합니다.

version = 5.6.0

버전 번호가 지정되면( version 또는 versionsym.qdocconf 변수를 사용하여) 지정하면 해당 \version 명령을 통해 문서에서 사용할 수 있습니다.

버전도 참조하세요.

versionsym

versionsym 변수는 문서화된 소프트웨어의 버전 번호를 정의하는 C++ 전처리기 심볼을 지정합니다.

versionsym = QT_VERSION_STR

QT_VERSION_STR qglobal.h에서 다음과 같이 정의됩니다.

#define QT_VERSION_STR   "5.14.1"

버전 번호가 지정되면 ( version 또는 versionsym.qdocconf 변수를 사용하여) 지정하면 해당 \version 명령을 통해 문서에서 사용할 수 있습니다.

버전도 참조하세요.

warninglimit

warninglimit 변수는 허용되는 문서 경고의 최대 개수를 설정합니다. 이 제한을 초과하면 QDoc은 정상적으로 계속 진행되지만 경고 개수를 오류 코드로 표시하고 종료됩니다. 제한을 초과하지 않았거나 warninglimit 가 정의되지 않은 경우 다른 심각한 오류가 없는 것으로 간주하여 QDoc 프로세스가 0으로 종료됩니다.

warninglimit 을 0 으로 설정하면 모든 경고에 대해 실패를 의미합니다.

예를 들어

# Fail the documentation build if we have more than 100 warnings
warninglimit = 100
warninglimit.enabled = true

warninglimit 변수는 Qt 5.11에 도입되었습니다.