1# Developing PETSc Documentation 2 3```{toctree} 4:maxdepth: 2 5``` 6 7## General Guidelines 8 9- Good documentation should be like a bonsai tree: alive, on display, frequently tended, and as small as possible (adapted from [these best practices](https://github.com/google/styleguide/blob/gh-pages/docguide/best_practices.md)). 10- Wrong, irrelevant, or confusing documentation is worse than no documentation. 11 12(sphinx_documentation)= 13 14## Documentation with Sphinx 15 16We use [Sphinx](https://www.sphinx-doc.org/en/master/) to build our web pages and documentation. Most content is written using [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), a simple markup language. 17 18[These slides](https://gitlab.com/psanan/petsc-sphinx-slides) contain an overview of Sphinx and how we use(d) it, as of October 2020. 19 20(sec_local_html_docs)= 21 22### Building the HTML docs locally 23 24We use a [Python 3 virtual environment](https://docs.python.org/3/tutorial/venv.html) to build the documentation since not all developers can trivially install the needed Python modules directly. 25 26```console 27$ cd $PETSC_DIR 28$ make docs 29$ open doc/_build/html/index.html # in a browser 30``` 31 32or 33 34```console 35$ cd $PETSC_DIR/doc 36$ make sphinxhtml 37$ open _build/html/index.html 38``` 39 40(sec_local_docs_latex)= 41 42### Building the manual locally as a PDF via LaTeX 43 44:::{admonition} Note 45Before following these instructions, you need to have a working 46local LaTeX installation and the ability to install additional packages, 47if need be, to resolve LaTeX errors. 48::: 49 50Set up your local Python environment (e.g., ref:`as above <sec_local_html_docs>`), then 51 52```console 53$ cd doc 54$ make sphinxpdf 55$ open _build/latex/manual.pdf # in PDF viewer 56``` 57 58(sphinx_guidelines)= 59 60### Sphinx Documentation Guidelines 61 62Refer to Sphinx's [own documentation](https://https://www.sphinx-doc.org) for general information on how to use Sphinx, and note the following additional guidelines. 63 64- Use the [literalinclude directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude) to directly include pieces of source code. Use a path beginning with `/`, relative to the root for the Sphinx docs (where `conf.py` is found). 65 66 ```rst 67 .. literalinclude:: /../src/sys/error/err.c 68 :start-at: PetscErrorCode PetscError( 69 :end-at: PetscFunctionReturn(PETSC_SUCCESS) 70 :append: } 71 ``` 72 73 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. Use the `:language:` option to appropriately highlight languages other than C. 74 75- Any invocable command line statements longer than a few words should be in 76 `.. code-block::` sections. Double backticks must enclose any such statements not in code-block statements"\`\`". For example `make all` is acceptable but 77 78 ```console 79 $ make PETSC_DIR=/my/path/to/petsc PETSC_ARCH=my-petsc-arch all 80 ``` 81 82 should be in a `.. code-block::`. 83 84- All code blocks showing command line invocation must use the "console" block 85 directive. E.g. 86 87 ```rst 88 .. code-block:: console 89 90 $ cd $PETSC_DIR/src/snes/interface 91 $ ./someprog 92 output1 93 output2 94 ``` 95 96 The only exception to this is when displaying raw output, i.e., with no preceding 97 commands. Then one may use just the "::" directive to improve visibility, e.g., 98 99 ```rst 100 :: 101 102 output1 103 output2 104 ``` 105 106- Any code blocks that show command line invocations must be preceded by `$`, e.g. 107 108 ```rst 109 .. code-block:: console 110 111 $ ./configure --some-args 112 $ make libs 113 $ make ./ex1 114 $ ./ex1 --some-args 115 ``` 116 117- Environment variables such as `$PETSC_DIR` or `$PATH` must be preceded by 118 `$` and be enclosed in double backticks, e.g. 119 120 ```rst 121 Set ``$PETSC_DIR`` and ``$PETSC_ARCH`` 122 ``` 123 124- For internal links, use explicit labels, e.g 125 126 ```rst 127 .. _sec_short_name: 128 129 Section name 130 ============ 131 ``` 132 133 and elsewhere (in any document), 134 135 ```rst 136 See :ref:`link text <sec_short_name>` 137 ``` 138 139- For internal links in the manual with targets outside the manual, always provide alt text 140 so that the text will be properly formatted in the {ref}`standalone PDF manual <sec_local_docs_latex>`, e.g. 141 142 > ```rst 143 > PETSc has :doc:`mailing lists </community/mailing>`. 144 > ``` 145 146- We use the [sphinxcontrib-bibtex extension](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/) 147 to include citations from BibTeX files. 148 You must include `.. bibliography::` blocks at the bottom of a page, including citations ([example](https://gitlab.com/petsc/petsc/-/raw/main/doc/manual/ksp.rst)). 149 To cite the same reference on more than one page, use [this workaround](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#key-prefixing) on one of them ([example](https://gitlab.com/petsc/petsc/-/raw/main/doc/developers/articles.rst)) [^bibtex-footnote]. 150 151- See special instructions on {any}`docs_images`. 152 153- Prefer formatting styles that are easy to modify and maintain. In particular, the use of [list-table](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) is recommended. 154 155- When using external links with inline URLs, prefer to use [anonymous hyperlink references](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks) with two trailing underscores, e.g. 156 157 ```rst 158 `link text <https://external.org>`__ 159 ``` 160 161- To pluralize something with inline markup, e.g. `DM`s, escape the trailing character to avoid `WARNING: Inline literal start-string without end-string`. 162 163 ```rst 164 ``DM``\s 165 ``` 166 167- Use restraint in adding new Sphinx extensions, in particular, those which aren't 168 widely used and well-supported, or those with hidden system dependencies. 169 170(petsc_repositories)= 171 172## Other PETSc repositories 173 174In addition to the [PETSc repository](https://gitlab.com/petsc/petsc), there are three other PETSc repositories which contain large data 175files that are unnecessary for most PETSc usages and thus are not stored in the main repository. 176 177- [Images](https://gitlab.com/petsc/images) contains images that are used in the PETSc documentation or have other uses. See {any}`docs_images` 178 for details on its use. 179- [Annual-Meetings](https://gitlab.com/petsc/annual-meetings) contains various documents from the {any}`meetings`. See {any}`docs_meetings`. 180- [Datafiles](https://gitlab.com/petsc/datafiles) contains large matrices, meshes, and various other data files that 181 are used in the {any}`PETSc CI<test_harness_data>`. 182- [Tutorials]((https://gitlab.com/petsc/annual-meetings) contains slides from {any}`tutorials`. See {any}`docs_tutorials`. 183 184Other repositories containing software PETSc uses are located at [GitLab](https://gitlab.com/petsc/) 185and [BitBucket](https://bitbucket.org/petsc/workspace/repositories). The BitBucket location is used for historical reasons, 186there are many links on the web to these locations thus the repositories have not been migrated to GitLab. 187 188(docs_images)= 189 190## Images 191 192PETSc's documentation is tightly coupled to the source code and tests and 193is tracked in the primary PETSc Git repository. However, image files are 194too large to track directly this way (especially because they persist in the integration branches' histories). Thus we do not put images 195into the PETSc git repository. 196 197Therefore, we store image files in a separate Git repository, [Images](https://gitlab.com/petsc/petsc). This repository is automatically cloned 198(if not already available) and updated when building the documentation. It can also be cloned by running 199`make images` in the `doc/` directory. 200Any new images required must be added to the currently-used branch of this repository. 201 202### Image Guidelines 203 204- Whenever possible, use SVG files. SVG is a web-friendly vector format and will be automatically converted to PDF using `rsvg-convert` [^svg-footnote] 205- Avoid large files and large numbers of images. 206- Do not add movies or other non-image files. 207 208### Adding new images 209 210- Decide where in `doc/images` a new image should go. Use the structure of the `doc/` tree as a guide. 211- Create a Merge Request to the currently-used branch of the upstream images repository, adding this image [^maintainer-fast-image-footnote]. 212- Once this Merge Request is merged, you may make a MR on the main PETSc Git repository relying on the new image(s). 213 214It may be helpful to place working copies of the new image(s) in your local `doc/images` 215while iterating on documentation; don't forget to update the upstream images repository. 216 217### Removing, renaming, moving, or updating images 218 219Do not directly move, rename, or update images in the images repository. 220Simply add a logically-numbered new version of the image. 221 222If an image is not used in *any* {any}`integration branch <sec_integration_branches>` (`main` or `release`), 223add it to the top-level list of files to delete in the images repository. 224 225(docs_images_cleanup)= 226 227### Cleaning up the images repository (maintainers only) 228 229If the size of the image repository grows too large, 230 231- Create a new branch `main-X`, where `X` increments the current value 232- Create a new commit deleting all files in the to-delete list and clearing the list 233- Reset the new `main-X` to a single commit with this new, cleaned-up state 234- Set `main-X` as the "default" branch on GitLab. 235- Update both `release` and `main` in the primary PETSc repository to clone this new branch 236 237(docs_meetings)= 238 239## Annual meetings website 240 241Like {any}`docs_images` the material (slides, etc.) for the PETSc annual meetings is too large to store in the primary PETSc Git repository. 242It is stored in [Annual-Meetings](https://gitlab.com/petsc/annual-meetings) repository and linked from {any}`meetings`. 243 244The files are all in the public directory of the repository so that the `.gitlab-ci.yml` file for the repository 245automatically displays all the files at https://petsc.gitlab.io/annual-meetings. Thus, all one needs to do is add files into 246[Annual-Meetings](https://gitlab.com/petsc/annual-meetings) and provide appropriate links within that repository or from {any}`meetings` 247in the primary PETSc Git repository. 248 249(docs_tutorials)= 250 251## Tutorials website 252 253Like {any}`docs_meetings` the material (slides, etc.) for the PETSc tutorials is too large to store in the primary PETSc Git repository. 254It is stored in [Tutorials](https://gitlab.com/petsc/tutorials) repository and linked from {any}`tutorials`. 255 256The files are all in the public directory of the repository so that the `.gitlab-ci.yml` file for the repository 257automatically displays all the files at https://petsc.gitlab.io/tutorials. Thus, all one needs to do is add files into 258[Tutorials](https://gitlab.com/petsc/tutorials) and provide appropriate links within that repository or from {any}`tutorials` 259in the primary PETSc Git repository. 260 261(manpages_c2html_build)= 262 263## Building Manual Pages and C2HTML Files 264 265The manual pages and C2HTML-generated file as built in a process described below using the documentation tools listed below, which are 266automatically downloaded and installed if needed while building the PETSc documentation./ 267 268- [Sowing](https://bitbucket.org/petsc/pkg-sowing): Developed by Bill Gropp, this produces the PETSc manual pages; see the [Sowing documentation](http://wgropp.cs.illinois.edu/projects/software/sowing/doctext/doctext.htm) and {ref}`manual_page_format`. 269- [C2html](https://gitlab.com/petsc/pkg-c2html): This generates the HTML versions of all the source code. 270 271Sowing and C2html are build tools that do not use the compilers specified to PETSc's `configure`, as they 272need to work in cross-compilation environments. Thus, they default to using `gcc`, `g++`, and `flex` from 273the user's environment (or `configure` options like `--download-sowing-cxx`). Microsoft Windows users must install `gcc` 274etc., from Cygwin in order to be able to build the documentation. 275 276```{rubric} Footnotes 277``` 278 279[^bibtex-footnote]: The extensions's [development branch](https://github.com/mcmtroffaes/sphinxcontrib-bibtex) [supports our use case better](https://github.com/mcmtroffaes/sphinxcontrib-bibtex/pull/185) (`:footcite:`), which can be investigated if a release is ever made. This stuff is now in the main repository but does not work as advertised from .md files. 280 281[^svg-footnote]: `rsvg-convert` is installable with your package manager, e.g., `librsvg2-bin` on Debian/Ubuntu systems). 282 283[^maintainer-fast-image-footnote]: Maintainers may directly push commits. 284