Qt Documentation: Project Structure: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Convert ExpressionEngine section headers)
 
(4 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Cleanup | reason=Auto-imported from ExpressionEngine.}}
[[Category:Writing Guidelines]]
 
= Documentation Structure =
This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]].
This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]].


Line 62: Line 60:
== Snippet and Example Relative Paths ==
== Snippet and Example Relative Paths ==


QDoc uses the [http://doc-snapshot.qt.io/qdoc/qdoc-guide-conf.html qdocconf] file to retrieve examples, snippets, and the source code.
QDoc uses the [http://doc-snapshot.qt.io/qdoc/qdoc-guide-conf.html 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.
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:
Using Qt SQL's qdocconf file as an example:
<code>
<code lang="make">
exampledirs += ../../../examples/sql  snippets/
exampledirs += ../../../examples/sql  snippets/
</code>
</code>

Latest revision as of 12:40, 8 May 2023

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.