Developing PETSc Documentation

General Guidelines

  • Good documentation should be like a bonsai tree: alive, on display, frequently tended, and as small as possible (adapted from these best practices).

  • Wrong, irrelevant, or confusing documentation is worse than no documentation.

Building Main Documentation

The documentation tools listed below (except for pdflatex) are automatically downloaded and installed by ./configure.

  • Sowing: a text processing tool developed by Bill Gropp. This produces the PETSc manual pages; see the Sowing documentation and Manual Page Format.

  • C2html: A text processing package. This generates the HTML versions of all the source code.

  • A version of pdflatex, for example in Tex Live. This package might already be installed on most systems. It is required to generate the users manual (part of the PETSc documentation).

Note: Sowing and c2html have additional dependencies like gcc, g++, and flex and do not use compilers specified to PETSc configure. [Windows users please install the corresponding cygwin packages]

Once pdflatex is in your PATH, you can build the documentation with:

make alldoc LOC=${PETSC_DIR}

(Note that this does not include Sphinx Documentation).

To get a quick preview of manual pages from a single source directory (mainly to debug the manual page syntax):

cd $PETSC_DIR/src/snes/interface
make LOC=$PETSC_DIR manualpages_buildcite
browse $PETSC_DIR/docs/manualpages/SNES/SNESCreate.html  # or suitable command to open the HTML page in a browser

Sphinx Documentation

Sphinx is a well-documented and widely-used set of Python-based tools for building documentation. Most content is written using reStructuredText, a simple markup language.

The Sphinx documentation is currently not integrated into the main docs build as described in Building Main Documentation.

ReadTheDocs generates the HTML documentation at https://docs.petsc.org from the PETSc Git repository. A version of the documentation can be built there, corresponding to any Git branch, which is useful if developing a large set of documentation changes.

We also use Sphinx to generate a PDF version of the User Manual, via LaTeX.

These slides contain an overview of Sphinx and how it’s used in PETSc, as of October, 2020.

Making changes to the Sphinx Docs from the web

You can make small changes this documentation entirely through web interfaces, using the usual guidelines in PETSc Integration Workflows (note the options for speedy review of docs-only changes).

  1. Find the page of interest, confirming the version is what you expect (usually “latest”).

  2. In the small ReadTheDocs menu in the bottom right, click the link to edit on GitLab.

  3. Make your changes.

  4. Compose a commit message and name your branch.

  5. Click the button to commit changes and create a Merge Request.

Building the Sphinx docs locally

  • Make sure that you have Python 3 and the required modules, as listed in the ReadTheDocs configuration file and requirements file [#f1]. e.g. with pip, pip install -r $PETSC_DIR/src/docs/sphinx_docs/requirements.txt.

  • Navigate to the location of conf.py for the Sphinx docs (currently $PETSC_DIR/src/docs/sphinx_docs).

  • make html

  • Open _build/html/index.html with your browser.

Sphinx Documentation Guidelines

  • Use the literalinclude directive to directly include pieces of source code, as in the following example. Note that an “absolute” path has been used, which means relative to the root for the Sphinx docs (where conf.py is found).

    .. literalinclude:: /../../../src/sys/error/err.c
   :start-at: PetscErrorCode PetscError(
   :end-at: PetscFunctionReturn(0)
   :append: }

    For robustness to changes in the source files, Use :start-at: and related options when possible, noting that you can also use (positive) values of :lines: relative to this. For languages other than C, use the :language: option to appropriately highlight.

  • We use the sphinxcontrib-bibtex extension to include citations from BibTeX files. You must include .. bibliography:: blocks at the bottom of a page including citations (example). To cite the same reference in more than one page, use this workaround on one of them (example) 1.

  • When possible, please use SVG for images. SVG is web-friendly and will be automatically converted to PDF using rsvg-convert (installable with your package manager, e.g., librsvg2-bin on Debian/Ubuntu systems). If SVG originals are not available, it is useful to provide images in both web-friendly (such as PNG) and PDF formats. This can be done with a wildcard extension, as in the following example, which uses ghost.png for the web but ghost.pdf when building a PDF with LaTeX.

    .. figure:: ghost.*
   :alt: Ghost Points

   Ghost Points

  • Prefer formatting styles that are easy to modify and maintain. In particular, use of list-table is recommended.

    .. list-table::
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

    which renders as

    Treat

    Quantity

    Description

    Albatross

    2.99

    On a stick!

    Crunchy Frog

    1.49

    If we took the bones out, it wouldn’t be crunchy, now would it?

    Gannet Ripple

    1.99

    On a stick!

  • When using external links with inline URLs, prefer to use anonymous hyperlink references with two trailing underscores, e.g.

    `link text <https://external.org>`__

Porting LaTeX to Sphinx

These are instructions relevant to porting the Users manual from its previous LaTeX incarnation, to Sphinx (as here). This section can be removed once the manual and TAO manual are ported.

The first steps are to modify the LaTeX source to the point that it can be converted to RST by Pandoc.

  • Copy the target file, say cp manual.tex manual_consolidated.tex

  • copy all files used with \input into place, using e.g. part1.tex instead of part1tmp.tex (as we don’t need the HTML links)

  • Remove essentially all of the preamble, leaving only \documentclass{book} followed by \begin{document}

  • Save a copy of this file, say manual_to_process.tex.

  • Perform some global cleanup operations, as with this script

    #!/usr/bin/env bash

target=${1:-manual_to_process.tex}
sed=gsed  # change this to sed on a GNU/Linux system

# \trl{foo} --> \verb|foo|
# \lstinline{foo} --> \lstinline|foo|
# only works if there are no }'s inside, so we take care of special cases beforehand,
# of the form \trl{${PETSC_DIR}/${PETSC_ARCH}/bar/baz} and \trl{${FOO}/bar/baz}

${sed} -i 's/\\trl{${PETSC_DIR}\/${PETSC_ARCH}\([^}]*\)}/\\verb|${PETSC_DIR}\/${PETSC_ARCH}\1|/g' ${target}
${sed} -i 's/\\trl{${\([^}]*\)}\([^}]*\)}/\\verb|${\1}\2|/g' ${target}

${sed} -i       's/\\trl{\([^}]*\)}/\\verb|\1|/g' ${target}
${sed} -i 's/\\lstinline{\([^}]*\)}/\\verb|\1|/g' ${target}

${sed} -i 's/\\lstinline|/\\verb|/g' ${target}

${sed} -i 's/tightitemize/itemize/g' ${target}
${sed} -i 's/tightenumerate/enumerate/g' ${target}

${sed} -i 's/lstlisting/verbatim/g' ${target}
${sed} -i 's/bashlisting/verbatim/g' ${target}
${sed} -i 's/makelisting/verbatim/g' ${target}
${sed} -i 's/outputlisting/verbatim/g' ${target}
${sed} -i 's/pythonlisting/verbatim/g' ${target}

  • Fix any typos like this (wrong right brace) : PetscViewerPushFormat(viewer,PETSC_VIEWER_BINARY_MATLAB} These will produce very unhelpful Pandoc error messages at the end of the file like Error at "source" (line 4873, column 10): unexpected end of input %%% End:

  • Convert to .rst with pandoc (tested with v2.9.2), e.g. pandoc -s -t rst -f latex manual_to_process.tex -o manual.rst.

  • Move to Sphinx docs tree (perhaps renaming or splitting up) and build.

Next, one must examine the output, ideally comparing to the original rendered LaTeX, and make fixes on the .rst file, including but not limited to:

  • Check links

  • Add correct code block languages when not C, e.g. replace :: with .. code-block:: bash

  • Re-add citations with :cite: and add per-chapter bibliography sections (see existing examples)

  • Fix footnotes

  • Fix section labels and links

  • Fix links with literals in the link text

  • Itemized lists

  • Replace Tikz with graphviz (or images or something else)

  • Replace/fix tables

  • Replace included source code with “literalinclude” (see Sphinx Documentation Guidelines)

  • (please add more common fixes here as you find them) …

Footnotes

1

The extensions’s development branch supports our use case better (:footcite:), which can be investigated if a release is ever made.

2

We use a precise version of Sphinx to avoid issues with our custom extension to create inline links