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.
Documentation with Sphinx#
We use Sphinx to build our web page and documentation. Most content is written using reStructuredText, a simple markup language.
These slides contain an overview of Sphinx and how we use(d) it, as of October, 2020.
Building the HTML docs locally#
Note
The documentation build with Sphinx involves configuring a minimal build
of PETSc and building some of the classic docs,
which requires local working flex
, gcc
, and g++
before
you follow the instructions below.
We suggest using a Python 3 virtual environment 1.
$ cd $PETSC_DIR
$ python3 -m venv petsc-doc-env
$ . petsc-doc-env/bin/activate
$ pip install -r doc/requirements.txt
Then,
$ cd doc
$ make html # may take several minutes
$ browse _build/html/index.html # or otherwise open in browser
to turn off the Python virtual environment once you have built the documentation use
$ deactivate
Building the manual locally as a PDF via LaTeX#
Note
Before following these instructions, you should have a working local LaTeX installation and the ability to install additional packages, if need be, to resolve LaTeX errors.
Set up your local Python environment (e.g. as above), then
$ cd doc
$ make latexpdf
$ open _build/latex/manual.pdf # or otherwise open in PDF viewer
Sphinx Documentation Guidelines#
Refer to Sphinx’s own documentation for general information on how to use Sphinx, and note the following additional guidelines.
Use the literalinclude directive to directly include pieces of source code. Use an “absolute” path, beginning with
/
, which means relative to the root for the Sphinx docs (whereconf.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.Any invocable command line statements longer than a few words should be in
.. code-block::
sections. Any such statements not in code-block statements must be enclosed by double backticks “``”. For examplemake all
is acceptable but$ make PETSC_DIR=/my/path/to/petsc PETSC_ARCH=my-petsc-arch all
should be in a block.
All code blocks showing invocation of command line must use the “console” block directive. E.g.
.. code-block:: console $ cd $PETSC_DIR/src/snes/interface $ ./someprog output1 output2
The only exception of this is when displaying raw output, i.e. with no preceding commands. Then one may use just the “::” directive to improve visibility E.g.
:: output1 output2
Any code blocks that show command line invocations must be preceded by
$
, e.g... code-block:: console $ ./configure --some-args $ make libs $ make ./ex1 $ ./ex1 --some-args
Environment variables such as
$PETSC_DIR
or$PATH
must be preceded by$
and be enclosed in double backticks, e.g.Set ``$PETSC_DIR`` and ``$PETSC_ARCH``
For internal links, use explicit labels, e.g
.. _sec_short_name: Section name ============
and elsewhere (in any document),
See :ref:`link text <sec_short_name>`
For internal links in the manual with targets outside the manual, always provide alt text so that the text will be properly formatted in the standalone PDF manual, e.g.
PETSc has :doc:`mailing lists </community/mailing>`.
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) 2.See special instructions on Images.
Prefer formatting styles that are easy to modify and maintain. In particular, use of list-table is recommended.
When using external links with inline URLs, prefer to use anonymous hyperlink references with two trailing underscores, e.g.
`link text <https://external.org>`__
To pluralize something with inline markup, e.g.
DM
s, escape the trailing character to avoidWARNING: Inline literal start-string without end-string
.``DM``\s
Use restraint in adding new Sphinx extensions, in particular those which aren’t widely-used and well-supported, or those with hidden system dependencies.
Images#
PETSc’s documentation is tightly coupled to the source code and tests, and is tracked in the primary PETSc Git repository. However, image files are too large to directly track this way (especially because they persist in the integration branches’ histories).
Therefore, we store image files in a separate git repository and clone it when needed. Any new images required must added the currently-used branch of this repository.
Image Guidelines#
Whenever possible, use SVG files. SVG is a web-friendly vector format and will be automatically converted to PDF using
rsvg-convert
3Avoid large files and large numbers of images.
Do not add movies or other non-image files.
Adding new images#
Note the URL and currently-used branch (after
-b
) for the upstream images repository, as used by the documentation build:
git clone https://gitlab.com/petsc/images.git -b main-1 --depth=1 images
Decide where in
doc/images
a new image should go. Use the structure of thedoc/
tree itself as a guide.Create a Merge Request to the currently-used branch of the upstream images repository, adding this image 4.
Once this Merge Request is merged, you may make a Merge Request to the primary PETSc repository, relying on the new image(s).
It may be helpful to place working copies of new image(s) in your local doc/images
while iterating on documentation; just don’t forget to update the upstream images repository.
Removing, renaming, moving or updating images#
Do not directly move, rename, or update images in the images repository. Simply add a logically-numbered new version of the image.
If an image is not used in any integration branch (main
or release
),
add it to the the top-level list of files to delete, in the images repository.
Cleaning up the images repository (maintainers only)#
If the size of the image repository grows too large,
Create a new branch
main-X
, whereX
increments the current valueCreate a new commit deleting all files in the to-delete list and clearing the list
Reset the new
main-X
to a single commit with this new, cleaned-up stateSet
main-X
as the “default” branch on GitLab (or wherever it is hosted).Update both
release
andmain
in the primary PETSc repository to clone this new branch
Building Classic Documentation#
Some of the documentation is built by a “classic” process as described below.
The documentation tools listed below can be
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.
Note that Sowing and C2html are build tools that do not use the compilers specified to PETSc’s configure
, as they
need to work in cross-compilation environments. Thus, they default to using gcc
, g++
, and flex
from
the user’s environment (or configure
options like --download-sowing-cxx
). Microsoft Windows users should install gcc
etc. from Cygwin as these tools don’t build with MS compilers.
One can run this process in-tree with
$ make alldoc12 LOC=${PETSC_DIR}
For debugging, a quick preview of manual pages from a single source directory can be obtained, e.g.
$ cd $PETSC_DIR/src/snes/interface
$ make LOC=$PETSC_DIR manualpages_buildcite
$ browse $PETSC_DIR/docs/manualpages/SNES/SNESCreate.html # or otherwise open in browser
Footnotes
- 1
This requires Python 3.3 or later, and you maybe need to install a package like
python3-venv
.- 2
The extensions’s development branch supports our use case better (
:footcite:
), which can be investigated if a release is ever made.- 3
rsvg-convert
is installable with your package manager, e.g.,librsvg2-bin
on Debian/Ubuntu systems).- 4
Maintainers may directly push commits.