|
|
              
Creating QDoc Configuration FilesTo generate documentation, QDoc uses configuration files, with the qdocconf extension, to store configuration settings. The The QDoc Configuration File article covers the various configuration variables in greater detail. QDoc Configuration FilesQDoc'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 DITA XML format. The main distinction between the two outputs is that HTML documentation needs to have its HTML styling information in the configuration files. DITA XML documentation does not, and a separate process can style the documentation in DITA at a later time. DITA XML is 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. Project InformationQDoc uses the project information to generate the documentation. project = QDoc Project description = Sample QDoc project Input and Output DirectoriesSpecifying 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 variable. 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. Note: During each QDoc run, the output directory is deleted. Extra FilesQDoc will output generated documentation into the directory specified in the output directory. It is also possible to specify extra files that QDoc should export. extraimages.HTML = extraImage.png \ extraImage2.png The extraImage.png and the extraImage2.png files will be copied to the HTML output directory. Qt Help Framework ConfigurationQDoc 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 Creating Help Project Files article covers the configuration options. HTML ConfigurationQDoc 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 variable. 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, and a style directory, containing scripts and CSS files. HTML.templatedir = <path to templates> The main configuration variables are: HTML.postheader HTML.postpostheader HTML.postheader HTML.footer HTML.headerstyles HTML.stylesheets = style.css \ style1.css HTML.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 HTML Specific Configuration Variables article outlines the usage of each variable. DITA XML ConfigurationDITA XML output is enabled using the outputformats variable. Unlike HTML documentation, QDoc does not need HTML style templates for generating documentation in DITA XML format. outputformats = DITAXML
outputdir
Qt Index ReferenceDocumentation projects can link to Qt APIs and other articles by specifying the path to the qt.index file. When qdoc generates the Qt Reference Documentation, it will also generate an index file, containing the URLs to the articles. Other projects can use the links in the index file so that they can link to other articles and API documentation within Qt. indexes = $QT_INSTALL_DOCS/html/qt.index $OTHER_PROJECT/html/qt.index It is possible to specify multiple index files from several projects. Macros and Other ConfigurationsMacros 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 Π in the HTML file, which will appear as the Greek Π symbol when viewed in browsers. QML AdditionsQDoc 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 variable. Also, the generated HTML files can have a prefix, specified in the QDoc configuration file. outputprefixes = QML outputprefixes.QML = uicomponents- The outputprefixes will, for example, prefix QML type HTML filenames. files:
uicomponents-button.html
uicomponents-scrollbar.html
|
