Using Sphinx to Document Modules and Folders#

Note

This document assumes you are already familiar with the Restructured Text format. Some sources for help can be

found at:

Adding Documentation to a Module#

Assuming you want to document a Xmera module called genericModule. This means that the folder genericModule contains the files:

  • genericModule.c/cpp

  • genericModule.h

  • genericModule.i

Simply add the the desired module documentation as genericModule.rst to this folder. The cModuleTemplate has a sample module documentation file that you can copy into your folder. This content will be parsed ahead of the module function descriptions. When running cmake the genericModule.rst file should be included in the IDE such as Xcode if the module is a C++ module.

Adding Documentation to a Folder#

Some modules in Xmera are organized into sub-folders. If you want to add documentation to a particular sub-folder, as is done with Folder_power found at src/simulation/power, then add the name the restructured text file inside that folder and call it _doc.rst. If a file with this name is found, then its contents will be parsed ahead of show the folders files or sub-folders.

Overriding the Folder’s Auto-Generated index.rst File#

In some cases, such as with the Xmera example scripts folder in xmera/examples, we want to over-ride the auto-generated index.rst file with a custom file to control how the folder contents is rendered. This is done by placing a restructured text file called _default.rst inside this folder. The sample output can be found in examples.