Qt Documentation: Project Structure: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
No edit summary
Line 1: Line 1:
=Documentation Structure=
h1. Documentation Structure


This page is part of the [[QtWritingGuidelines|Qt Writing Guidelines]].
This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]].


Qt’s Reference Documentation consists of:
Qt's Reference Documentation consists of:<br />* API Documentation<br />* Overviews<br />* Examples


* <span class="caps">API</span> Documentation
== Modularized 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.


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:<br /><code><br />qtbase/<br /> doc/ #for documentation templates<br /> global/ #where the documentation templates are located<br /> src/<br /> network/<br /> doc/<br /> images/<br /> snippets/<br /> src/<br /> bearermanagement.qdoc<br /> network-programming.qdoc<br /> qtnetwork.qdoc # Qt Network landing page<br /> ssl.qdoc<br /> qtnetwork.qdocconf<br /> sql/<br /> doc/<br /> images/<br /> snippets/<br /> snippetA.qdoc # snippet file<br /> src/<br /> qsqldatatype-table.qdoc<br /> qtsql.qdoc # Qt SQL landing page<br /> sql-driver.qdoc<br /> sql-programming.qdoc<br /> qtsql.qdocconf # Qt SQL QDoc configuration file<br /> examples/ # example directory<br /> network/<br /> sql/<br /> exampleA/<br /> exampleA.pro # project file which must match the directory name<br /> main.cpp # source code<br /> doc/<br /> src/<br /> .qdoc # documentation for exampleA<br /> snippets/<br /> images/ #images used by the example's documentation<br /> screenshot.png<br /> exampleB/<br /> doc/<br /> src/<br /> .qdoc # documentation for exampleB<br /> images/<br /> snippets/<br /></code>
 
== Snippet and Example Relative Paths ==


Here is the basic structure, taking the qt5/qtbase directory as an example:<br />
QDoc uses the &quot;qdocconf&amp;quot;:http://doc-snapshot.qt.io/qdoc/qdoc-guide-conf.html file to retrieve examples, snippets, and the source code.<br />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.


==Snippet and Example Relative Paths==
Using Qt SQL's qdocconf file as an example:<br /><code><br />exampledirs += ../../../examples/sql  snippets/<br /></code>


QDoc uses the [http://doc-snapshot.qt.io/qdoc/qdoc-guide-conf.html qdocconf] ''[doc-snapshot.qt.io]'' file to retrieve examples, snippets, and the source code.<br /> In particular, the '''exampledirs''' variable holds the paths to the examples and snippets. The '''\example''' and '''\snippet''' commands’ arguments are relative paths that point to the snippet file or example directory.
This would allow the documentation to use:<br /><code><br />snippetA.qdoc main


Using Qt <span class="caps">SQL</span>’s qdocconf file as an example:<br />
exampleA


This would allow the documentation to use:<br /> Note that qdoc assumes that there are doc/src, doc/images, and doc/snippets directories in each example.
screenshot.png<br /></code><br />Note that qdoc assumes that there are doc/src, doc/images, and doc/snippets directories in each example.


==Overview documentation==
== Overview documentation ==


Some documentation encompasses several modules. This can be demos and overview documentation and tutorials for example.<br /> These should be in the qdoc repository which contains documentation that should be built last.
Some documentation encompasses several modules. This can be demos and overview documentation and tutorials for example.<br />These should be in the qdoc repository which contains documentation that should be built last.

Revision as of 10:05, 24 February 2015

h1. Documentation Structure

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:

<br />qtbase/<br /> doc/ #for documentation templates<br /> global/ #where the documentation templates are located<br /> src/<br /> network/<br /> doc/<br /> images/<br /> snippets/<br /> src/<br /> bearermanagement.qdoc<br /> network-programming.qdoc<br /> qtnetwork.qdoc # Qt Network landing page<br /> ssl.qdoc<br /> qtnetwork.qdocconf<br /> sql/<br /> doc/<br /> images/<br /> snippets/<br /> snippetA.qdoc # snippet file<br /> src/<br /> qsqldatatype-table.qdoc<br /> qtsql.qdoc # Qt SQL landing page<br /> sql-driver.qdoc<br /> sql-programming.qdoc<br /> qtsql.qdocconf # Qt SQL QDoc configuration file<br /> examples/ # example directory<br /> network/<br /> sql/<br /> exampleA/<br /> exampleA.pro # project file which must match the directory name<br /> main.cpp # source code<br /> doc/<br /> src/<br /> .qdoc # documentation for exampleA<br /> snippets/<br /> images/ #images used by the example's documentation<br /> screenshot.png<br /> exampleB/<br /> doc/<br /> src/<br /> .qdoc # documentation for exampleB<br /> images/<br /> snippets/<br />

Snippet and Example Relative Paths

QDoc uses the "qdocconf&quot;:http://doc-snapshot.qt.io/qdoc/qdoc-guide-conf.html 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:

<br />exampledirs += ../../../examples/sql  snippets/<br />

This would allow the documentation to use:

<br />snippetA.qdoc main

exampleA

screenshot.png<br />


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.