To generate documentation, QDoc uses configuration files, with the
qdocconf
extension, to store configuration settings.
The QDoc 配置文件 article covers the various configuration variables in greater detail.
QDoc's configuration settings can reside in a single
qdocconf
file, but can also be in other qdocconf files. The
include(<filepath>)
command allows configuration files to include other configuration files.
QDoc has two outputs, HTML documentation and documentation in DocBook XML format. The main distinction between the two outputs is that HTML documentation needs to have its HTML styling information in the configuration files. DocBook documentation does not, and a separate process can style the documentation in DocBook at a later time. DocBook therefore more flexible in allowing different styles to apply to the same information.
To run QDoc, the project configuration file is supplied as an argument.
qdoc project.qdocconf
The project configuration contains information that QDoc uses to create the documentation.
QDoc uses the
project
information to generate the documentation.
project = QDoc Project description = Sample QDoc project
Specifying the path to the source directories allow QDoc to find sources and generate documentation.
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 will process headers and sources from the ones specified in the
fileextensions
变量。
Likewise, QDoc needs the path to the output directory. The
outputformats
variable determines the type of documentation. These variables should be in separate configuration files to modularize the documentation build.
outputdir = $SAMPLE_PROJECT/doc/html outputformats = HTML
QDoc can resolve the paths relative to the qdocconf file as well as environment variables.
注意: During each QDoc run, the output directory is deleted.
QDoc will output generated documentation into the directory specified in the output directory. It is also possible to specify extra files that QDoc should export.
HTML.extraimages = extraImage.png \ extraImage2.png
The
extraImage.png
和
extraImage2.png
files will be copied to the HTML output directory.
QDoc will also export a
Qt Help Project
file, in a
qhp
file. The qhp file is then used by the
qhelpgenerator
to package the documentation into a
qch
file. Qt Creator and Qt Assistant reads the qch file to display the documentation.
The 创建帮助工程文件 article covers the configuration options.
QDoc has an HTML generator that will export a set of documentation into HTML files using various configuration settings. QDoc will place the generated documentation into the directory specified by the
outputdir
变量。
outputformats = HTML outputdir = <path to output directory>
QDoc needs to know where the styles and templates for generating HTML are located. Typically, the templates directory contains a
scripts
,
images
,和
style
directory, containing scripts and CSS files.
The main configuration variables are:
HTML.postheader HTML.postpostheader HTML.postheader HTML.footer HTML.headerstyles HTML.stylesheets = template/style/style.css \ template/style/style1.css HTML.scripts = template/scripts/script.js
The
HTML.headerstyles
variable inserts the style information into the HTML file and the
HTML.stylesheets
specifies which files QDoc should copy into the output directory. As well, QDoc will embed the string in the
postheader
,
footer
, and related variables into each HTML file.
The 特定格式配置变量 article outlines the usage of each variable.
Documentation projects can link to targets in other projects by specifying a set of dependencies, or a set of direct paths to index file(s) this project depends on. When QDoc generates documentation for a project, it will also generate an
.index
file containing URLs to each linkable entity in the project. Other projects can then define a dependency to the index file in order to link to the documentation within that project.
Macros for substituting HTML characters exist and are helpful for generating specific HTML-valid characters.
macro.pi.HTML = "Π"
The snippet code will replace any instances of
\\pi
with
&Pi
; in the HTML file, which will appear as the Greek Π symbol when viewed in browsers.
另请参阅: macro .
QDoc is able to parse QML files for QDoc comments. QDoc will parse files with the QML extension,
.qml
, if the extension type is included in the
fileextensions
变量。
Also, the generated HTML files can have a prefix and a suffix following the QML module name, specified in the QDoc configuration file.
outputprefixes = QML outputprefixes.QML = uicomponents- outputsuffixes = QML outputsuffixes.QML = -tp
另请参阅 : outputprefixes , outputsuffixes .
为 QDoc 安装 Clang Writing Documentation