Qt Documentation: Project Structure
This article may require cleanup to meet the Qt Wiki's quality standards. Reason: Auto-imported from ExpressionEngine. Please improve this article if you can. Remove the {{cleanup}} tag and add this page to Updated pages list after it's clean. |
This page is part of the Qt Writing Guidelines.
Qt's Reference Documentation consists of:
- API Documentation
- Overviews
- Examples
Modularized Documentation
The idea behind modularized documentation is that the documentation for the modules reside with the source code. As a result, moving a module will also move the documentation.
Here is the basic structure, taking the qt5/qtbase directory as an example:
qtbase/
doc/ #for documentation templates
global/ #where the documentation templates are located
src/
network/
doc/
images/
snippets/
src/
bearermanagement.qdoc
network-programming.qdoc
qtnetwork.qdoc # Qt Network landing page
ssl.qdoc
qtnetwork.qdocconf
sql/
doc/
images/
snippets/
snippetA.qdoc # snippet file
src/
qsqldatatype-table.qdoc
qtsql.qdoc # Qt SQL landing page
sql-driver.qdoc
sql-programming.qdoc
qtsql.qdocconf # Qt SQL QDoc configuration file
examples/ # example directory
network/
sql/
exampleA/
exampleA.pro # project file which must match the directory name
main.cpp # source code
doc/
src/
.qdoc # documentation for exampleA
snippets/
images/ #images used by the example's documentation
screenshot.png
exampleB/
doc/
src/
.qdoc # documentation for exampleB
images/
snippets/
Snippet and Example Relative Paths
QDoc uses the qdocconf file to retrieve examples, snippets, and the source code. In particular, the exampledirs variable holds the paths to the examples and snippets. The and commands' arguments are relative paths that point to the snippet file or example directory.
Using Qt SQL's qdocconf file as an example:
exampledirs += ../../../examples/sql snippets/
This would allow the documentation to use:
snippetA.qdoc main
exampleA
screenshot.png
Note that qdoc assumes that there are doc/src, doc/images, and doc/snippets directories in each example.
Overview documentation
Some documentation encompasses several modules. This can be demos and overview documentation and tutorials for example. These should be in the qdoc repository which contains documentation that should be built last.