Documenting the interface (Programmer’s reference)¶
The DOLFIN Programmer’s Reference is generated for the DOLFIN C++ library and Python module from the source code using the documentation tool Sphinx. This page describes how to generate the DOLFIN documentation locally and how to extend the contents of the Programmer’s Reference.
How to locally build the DOLFIN documentation¶
The DOLFIN documentation can be generated and built from the DOLFIN source directly as follows:
How to improve and extend the DOLFIN Programmer’s reference¶
The documentation contents are extracted from specially formatted comments (docstring comments) in the source code, converted to reStructuredText, and formatted using Sphinx. The syntax used for these specially formatted comments is described below.
To document a feature,
- Add appropriate docstring comments to source files (see Syntax for docstring comments).
- Build the documentation as described in How to locally build the DOLFIN documentation to check the result.
Syntax for docstring comments¶
Doxygen is used to parse the C++ header files for special comments,
we generally use comments starting with ///
. For information on
the required format, see the doxygen documentation
http://www.doxygen.org/manual/index.html
In addition we try to support some Sphinx syntax like
:math:`\lambda_3`
. We may add some more special tricks like raw
ReStructuredText passthrough, but in general you should stick to
normal doxygen syntax