QDoc 구성 파일 만들기

문서를 생성하기 위해 QDoc은 설정 정보를 저장하기 위해 확장자가 ` qdocconf `인 설정 파일을 사용합니다.

“QDoc 구성 파일” 문서에서는 다양한 구성 변수에 대해 더 자세히 다루고 있습니다.

QDoc 구성 파일

QDoc의 구성 설정은 하나의 qdocconf 파일에 포함될 수도 있지만, 다른 qdocconf 파일에 포함될 수도 있습니다. ` include(<filepath>) ` 명령을 사용하면 구성 파일에 다른 구성 파일을 포함시킬 수 있습니다.

QDoc은 HTML 문서와 DocBook XML 형식의 문서, 두 가지 출력 형식을 지원합니다. 이 두 출력 형식의 주요 차이점은 HTML 문서의 경우 구성 파일에 HTML 스타일 정보가 포함되어야 한다는 점입니다. 반면 DocBook 문서는 그렇지 않으며, 별도의 프로세스를 통해 나중에 DocBook 문서의 스타일을 지정할 수 있습니다. 따라서 DocBook은 동일한 정보에 서로 다른 스타일을 적용할 수 있다는 점에서 더 유연합니다.

QDoc을 실행하려면 프로젝트 설정 파일을 인수로 지정해야 합니다.

qdoc project.qdocconf

프로젝트 구성 파일에는 QDoc이 문서를 생성하는 데 사용하는 정보가 포함되어 있습니다.

프로젝트 정보

QDoc은 project 정보를 사용하여 문서를 생성합니다.

project = QDoc Project
description = Sample QDoc project

입력 및 출력 디렉터리

소스 디렉터리의 경로를 지정하면 QDoc이 소스 파일을 찾아 문서를 생성할 수 있습니다.

sourcedirs = <path to source code>
exampledirs = <path to examples directory>
imagedirs = <path to image directory>

sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml"
examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"

QDoc은 ` fileextensions ` 변수에 지정된 헤더 및 소스 파일을 처리합니다.

마찬가지로, QDoc에는 출력 디렉터리의 경로도 필요합니다. outputformats 변수는 문서 유형을 결정합니다. 문서 빌드를 모듈화하기 위해 이러한 변수들은 별도의 구성 파일에 포함되어야 합니다.

outputdir  =    $SAMPLE_PROJECT/doc/html
outputformats = HTML

QDoc은 qdocconf 파일 및 환경 변수를 기준으로 경로를 해결할 수 있습니다.

추가 파일

QDoc은 생성된 문서를 출력 디렉터리에 지정된 디렉터리에 출력합니다. 또한 QDoc이 내보내야 할 추가 파일을 지정할 수도 있습니다.

HTML.extraimages = extraImage.png \
                   extraImage2.png

extraImage.png 및 extraImage2.png 파일은 HTML 출력 디렉터리로 복사됩니다.

Qt Help 프레임워크 구성

QDoc은 또한 Qt Help 프로젝트 파일을 qhp 파일로 내보냅니다. 이 qhp 파일은 qhelpgenerator 에서 문서를 qch 파일로 패키징하는 데 사용됩니다. Qt Creator 및 Qt Assistant 은 qch 파일을 읽어 문서를 표시합니다.

'도움말 프로젝트 파일 만들기 ' 문서에서는 구성 옵션에 대해 설명합니다.

HTML 구성

QDoc에는 다양한 구성 설정을 사용하여 문서 세트를 HTML 파일로 내보내는 HTML 생성기가 있습니다. QDoc은 생성된 문서를 outputdir 변수로 지정된 디렉터리에 저장합니다.

outputformats = HTML
outputdir =  <path to output directory>

QDoc은 HTML 생성을 위한 스타일과 템플릿이 어디에 있는지 알아야 합니다. 일반적으로 템플릿 디렉터리에는 scripts, images, style 디렉터리가 포함되어 있으며, 여기에는 스크립트와 CSS 파일이 들어 있습니다.

주요 구성 변수는 다음과 같습니다:

HTML.postheader
HTML.postpostheader
HTML.footer

HTML.headerstyles
HTML.stylesheets = template/style/style.css \
                   template/style/style1.css

HTML.scripts = template/scripts/script.js

HTML.headerstyles 변수는 HTML 파일에 스타일 정보를 삽입하고, HTML.stylesheets 는 QDoc이 출력 디렉터리로 복사해야 할 파일을 지정합니다. 또한 QDoc은 postheader, footer 및 관련 변수에 포함된 문자열을 각 HTML 파일에 삽입합니다.

'형식별 구성 변수' 문서에서는 각 변수의 사용법을 설명합니다.

QDoc 인덱스 파일

문서화 프로젝트는 일련의 종속성을 지정하거나, 해당 프로젝트가 의존하는 인덱스 파일에 대한 일련의 직접 경로를 지정하여 다른 프로젝트의 대상에 링크할 수 있습니다. QDoc이 프로젝트에 대한 문서를 생성할 때, 프로젝트 내의 링크 가능한 각 개체에 대한 URL이 포함된 .index 파일도 함께 생성합니다. 그러면 다른 프로젝트에서 해당 인덱스 파일에 대한 의존성을 정의하여 해당 프로젝트 내의 문서로 링크할 수 있습니다.

참조: depends 및 indexes.

매크로 및 기타 구성

HTML 문자를 대체하는 매크로가 존재하며, 특정 HTML 유효 문자를 생성하는 데 유용합니다.

macro.pi.HTML         = "Π"

다음 코드 스니펫은 HTML 파일 내의 모든 \\pi 를 &Pi 로 대체하며, 브라우저에서 볼 때 그리스 문자 Π 기호로 표시됩니다.

참조: 매크로.

QML 추가 사항

QDoc은 QML 파일에서 QDoc 주석을 분석할 수 있습니다. QDoc은 파일 확장자 변수( fileextensions )에 QML 확장자가 포함되어 있는 경우, QML 확장자( .qml)를 가진 파일을 분석합니다.

또한, 생성된 HTML 파일에는 QDoc 구성 파일에서 지정한 QML 모듈 이름 앞에 접두사가, 뒤에 접미사가 붙을 수 있습니다.

outputprefixes = QML
outputprefixes.QML = uicomponents-
outputsuffixes = QML
outputsuffixes.QML = -tp

참조: outputprefixes, outputsuffixes.