16.3.3. Documentation Style
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.
16.3.3.1. File Structure
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.
16.3.3.1.1. Figures and other assets
Figures and other assets go under doc/shared/figs. Package specific figures go in the doc/shared/figs/<package> directory.
16.3.3.1.2. Documentation superbuild
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.
16.3.3.2. Headings
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.
16.3.3.3. Colors
Color Roles |
Text |
Color Italic Roles |
Text |
|
red |
|
red italic |
|
black |
|
black italic |
|
gray |
|
gray italic |
|
silver |
|
silver italic |
|
magenta |
|
magenta italic |
|
pink |
|
pink italic |
|
orange |
|
orange italic |
|
yellow |
|
yellow italic |
|
lime |
|
lime italic |
|
green |
|
green italic |
|
olive |
|
olive italic |
|
teal |
|
teal italic |
|
cyan |
|
cyan italic |
|
blue |
|
blue italic |
|
purple |
|
purple italic |
16.3.3.4. Capitalization
Special terms in the SUNDIALS documentation that should be capitalized: TODO: enumerate them
16.3.3.5. Footnotes
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.
16.3.3.6. References
All citations go into doc/shared/sundials.bib. TODO: add citation and reference key style.
16.3.3.7. Documenting Functions
16.3.3.7.1. Adding New Functions
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.
16.3.3.7.2. Changes to Existing Functions
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.
16.3.3.7.3. Deprecating Functions
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.