QDoc Project Templates: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
(Gather writing guidelines into a category)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=QDoc Project Templates=
[[Category:Writing Guidelines]]
 
{{LangSwitch}}
This page is part of the [[QtWritingGuidelines|Qt Writing Guidelines]].
This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]].


QDoc configuration may be imported by using '''include()'''. The templates may be referenced using environment variables, relevant paths, or absolute paths.
QDoc configuration may be imported by using '''include()'''. The templates may be referenced using environment variables, relevant paths, or absolute paths.
Line 7: Line 7:
'''Note''' This feature is only supported in Qt 5 that is not shadow-built.
'''Note''' This feature is only supported in Qt 5 that is not shadow-built.


==Qt 5 Module Defaults==
== Qt 5 Module Defaults ==


Projects that are part of Qt 5 as an Essential or Add-On can simply include the templates in Qt 5’s ''qtbase/doc/global'' directory. These projects should receive the '''QT_INSTALL_DOCS''' variable from QMake. See [[Checklist-for-Adding-Documentation-for-a-New-Module|Checklist for Adding Documentation for a New Module]]
Projects that are part of Qt 5 as an Essential or Add-On can simply include the templates in Qt 5's ''qtbase/doc/global'' directory. These projects should receive the '''QT_INSTALL_DOCS''' variable from QMake. See [[Checklist for Adding Documentation for a New Module]]


There are several templates in Qt 5, but the basic one which all Qt 5 modules should include is '''qt-module-defaults.qdocconf''':<br />
There are several templates in Qt 5, but the basic one which all Qt 5 modules should include is '''qt-module-defaults.qdocconf''':
<code>
include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
</code>


This template will include the necessary <span class="caps">HTML</span> templates, C++ macros, and other QDoc configurations.<br /> Note that this include should be at the top of the .qdocconf file.
This template will include the necessary HTML templates, C++ macros, and other QDoc configurations.
Note that this include should be at the top of the .qdocconf file.


'''Note''' Including this template also applies the Qt Project copyright notices which may not be appropriate for some projects.
'''Note''' Including this template also applies the Qt Project copyright notices which may not be appropriate for some projects.


==Projects Outside of Qt 5==
== Projects Outside of Qt 5 ==


For projects outside of Qt 5, the includes can vary, depending on which configuration is desired. For a typical project, the following should suffice:<br />
For projects outside of Qt 5, the includes can vary, depending on which configuration is desired. For a typical project, the following should suffice:
<code>
include($QT_INSTALL_DOCS/global/macros.qdocconf) #macros for QDoc commands
include($QT_INSTALL_DOCS/global/qt-cpp-defines.qdocconf) #needed by C++ projects
include($QT_INSTALL_DOCS/global/compat.qdocconf) #compatibility macros
include($QT_INSTALL_DOCS/global/fileextensions.qdocconf) #configuration common among QDoc projects
include($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf) #offline HTML template for documentation shipped to Qt Creator
</code>


===Customizing the <span class="caps">HTML</span> template===
=== Customizing the HTML template ===


It is possible to customize the look-and-feel of the <span class="caps">HTML</span> template by including different templates.
It is possible to customize the look-and-feel of the HTML template by including different templates.


# For projects that package documentation to Qt Assistant or Qt Creator:<br />
# For projects that package documentation to Qt Assistant or Qt Creator:
<code>
include($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf) #offline HTML template for documentation shipped to Qt Creator
</code>


# For projects that wish to look like the documentation snapshots (doc-snapshot.qt.io)<br />
# For projects that wish to look like the documentation snapshots (doc-snapshot.qt.io)
<code>
include($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf)
</code>


To further customize, the templates in '''1''' and '''2''' include several other<br /><span class="caps">HTML</span>-related configurations.
To further customize, the templates in '''1''' and '''2''' include several other
HTML-related configurations.

Latest revision as of 15:45, 25 November 2016

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

This page is part of the Qt Writing Guidelines.

QDoc configuration may be imported by using include(). The templates may be referenced using environment variables, relevant paths, or absolute paths.

Note This feature is only supported in Qt 5 that is not shadow-built.

Qt 5 Module Defaults

Projects that are part of Qt 5 as an Essential or Add-On can simply include the templates in Qt 5's qtbase/doc/global directory. These projects should receive the QT_INSTALL_DOCS variable from QMake. See Checklist for Adding Documentation for a New Module

There are several templates in Qt 5, but the basic one which all Qt 5 modules should include is qt-module-defaults.qdocconf:

include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)

This template will include the necessary HTML templates, C++ macros, and other QDoc configurations. Note that this include should be at the top of the .qdocconf file.

Note Including this template also applies the Qt Project copyright notices which may not be appropriate for some projects.

Projects Outside of Qt 5

For projects outside of Qt 5, the includes can vary, depending on which configuration is desired. For a typical project, the following should suffice:

include($QT_INSTALL_DOCS/global/macros.qdocconf) #macros for QDoc commands
include($QT_INSTALL_DOCS/global/qt-cpp-defines.qdocconf) #needed by C++ projects
include($QT_INSTALL_DOCS/global/compat.qdocconf) #compatibility macros
include($QT_INSTALL_DOCS/global/fileextensions.qdocconf) #configuration common among QDoc projects
include($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf) #offline HTML template for documentation shipped to Qt Creator

Customizing the HTML template

It is possible to customize the look-and-feel of the HTML template by including different templates.

  1. For projects that package documentation to Qt Assistant or Qt Creator:
include($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf) #offline HTML template for documentation shipped to Qt Creator
  1. For projects that wish to look like the documentation snapshots (doc-snapshot.qt.io)
include($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf)

To further customize, the templates in 1 and 2 include several other HTML-related configurations.