Style guide for reStructuredText with Sphinx. For the most part, we attempt to follow the Python developer's guide commentary on documentation (where relevant): https://devguide.python.org/documenting/#style-guide.
Each package in SUNDIALS has a directory within the doc folder,
because each package documentation can be compiled separately.
Shared documentation goes into the doc/shared directory and
can be included from the package documentation using the
Sphinx .. include::
directive. Generally speaking, the use
of symlinks to the doc/shared directory is discouraged.
However, for the figs folder, we allow it.
Figures and other assets go under doc/shared/figs. Package specific figures go in the doc/shared/figs/<package> directory.
An HTML build of the documentation can be generated that includes all of the package documentations (with shared parts unrepeated). This is what is built by readthedocs and what can be accessed at readthedocs.org/project/sundials.
Follow the Python documentation convention:
# with overline, for parts * with overline, for chapters =, for sections -, for subsections ^, for subsubsections ", for paragraphs
Note that by following this convention, the # headers should never occur in the package documentation directories. This is reserved for the documentation superbuild.
Special terms in the SUNDIALS documentation that should be capitalized: TODO: enumerate them
Sphinx footnotes do not compile when generating the PDF from Latex,
therefore the use of footnotes is entirely banned. Restructure the
text, use .. notes::
, or .. warning::
directives instead.
All citations go into doc/shared/sundials.bib. TODO: add citation and reference key style.
The documentation for new functions should include the .. versionadded::
directive at the end of the documentation text noting the package version
number in which the function was added.
If the signature or behavior of a function changes in any release the
.. versionchanged::
directive should be added to the function documentation
noting the package version number in which the change happened and describing
the change.
When a function is deprecated the .. deprecated::
directive should be added
to the function documentation noting the package version number in which the
function was deprecated and describing what function should be used instead
if appropriate.