The templates intended for Doxygen-based projects are located in the with_doxygen folder. The templates for the projects that do not use Doxygen are located in the without_doxygen folder.
You can also browse our GitHub Pages to see the output of these templates.
Use the following templates to describe a particular function or a class:
Function Templatefor projects with Doxygen and without DoxygenClass Templatefor projects with Doxygen and without Doxygen- the template to describe a group of functions with Doxygen
An example of topic in the existing API Reference that could be documented using these templates:
If you need to document enumeration types (enums), use the following:
- the template to describe of a single enumeration type with Doxygen and without Doxygen
- the template to describe a list of enumeration types with Doxygen and without Doxygen
Use the Group Template for Doxygen groups (modules).
Use the template for the main page to create an overall structure of your API Reference documentation and provide users with clear navigation.
A note on this template:
-
Use
:ref:directive to provide links to chapters:-
In your chapter RST file, you need to have
.. _chapter_name_link:line at the top of the file. -
Then you can use the following syntax to refer to that file from anywhere in your documentation:
:ref:`chapter_name_link`
-
These templates are used to create a chapter of your API Reference documentation. For each template there is an underlying assumption that you already have a folder with RST files that you want to place within the same chapter.
If you want to have a chapter for examples, namespaces, classes, or doxygen groups, refer to the following templates:
- a chapter with examples is created from the
examplesfolder - a chapter with namespaces is created from the
namespacesfolder - a chapter with Doxygen groups is created from the
groupsfolder
Note: We recommend using these folder names for consistency across libraries.
For API chapters that combine topics related to a particlar entity a type of object, use the following templates:
- a simple one that only creates a table of contents from all the topics in a particular folder
- the one with a hidden table of contents that you can use to provide more information about the chapter's content in a form of a table
Examples of topics in existing API References that could be documented using these templates:
To create a glossary of terms used across your API Reference documentation, choose one of the following templates:
- a simple glossary in which all terms are sorted alphabetically within a single list
- a glossary with multiple sections in which terms are split into thematic groups and sorted alphabetically within each one
These terms could be referenced from other topics in your API documentation using :term: directive.
The contents directive produces a local table of contents. Omit it if you only have one subsection.
.. contents::
:local:
:depth: 1
These templates use the following order of RST headers:
Level 1
=======
Level 2
*******
Level 3
-------
You should use RST Headers consistenly. If in your documentation you follow another order or another style, adjust these templates accordingly.
If your Doxygen comments already contain extensive descriptions for functions, classes, and other entities, you do not need to copy these descriptions in RST as well.
For example, this is a part of the function template:
Description
***********
[The description of the function.]
API
***
.. doxygenfunction:: the name of the function
:project: the name of the project
If doxygenfunction produces the description of the function that you find sufficient, omit the "Description" section.
API
***
.. doxygenfunction:: the name of the function
:project: the name of the project