doc/developers/documentation.md

9 - Good documentation should be like a bonsai tree: alive, on display, frequently tended, and as sma…
10 - Wrong, irrelevant, or confusing documentation is worse than no documentation.
14 ## Documentation with Sphinx
16 …Sphinx](https://www.sphinx-doc.org/en/master/) to build our web pages and documentation. Most cont…
18 [These slides](https://gitlab.com/psanan/petsc-sphinx-slides) contain an overview of Sphinx and how…
24 We use a [Python 3 virtual environment](https://docs.python.org/3/tutorial/venv.html) to build the …
60 ### Sphinx Documentation Guidelines  argument
62 Refer to Sphinx's [own documentation](https://https://www.sphinx-doc.org) for general information o…
64 - Use the [literalinclude directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/di…
68      :start-at: PetscErrorCode PetscError(
69      :end-at: PetscFunctionReturn(PETSC_SUCCESS)
73 …For robustness to changes in the source files, Use `:start-at:` and related options when possible,…
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 st…
79   $ make PETSC_DIR=/my/path/to/petsc PETSC_ARCH=my-petsc-arch all
82   should be in a `.. code-block::`.
84 - All code blocks showing command line invocation must use the "console" block
88   .. code-block:: console
106 - Any code blocks that show command line invocations must be preceded by `$`, e.g.
109   .. code-block:: console
111      $ ./configure --some-args
114      $ ./ex1 --some-args
117 - Environment variables such as `$PETSC_DIR` or `$PATH` must be preceded by
124 - For internal links, use explicit labels, e.g
139 - For internal links in the manual with targets outside the manual, always provide alt text
146 - We use the [sphinxcontrib-bibtex extension](https://sphinxcontrib-bibtex.readthedocs.io/en/latest…
148 …om of a page, including citations ([example](https://gitlab.com/petsc/petsc/-/raw/main/doc/manual/…
149 …-bibtex.readthedocs.io/en/latest/usage.html#key-prefixing) on one of them ([example](https://gitla…
151 - See special instructions on {any}`docs_images`.
153 - Prefer formatting styles that are easy to modify and maintain. In particular, the use of [list-ta…
155 - When using external links with inline URLs, prefer to use [anonymous hyperlink references](https:…
161 - To pluralize something with inline markup, e.g. `DM`s, escape the trailing character to avoid `WA…
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.
177 - [Images](https://gitlab.com/petsc/images) contains images that are used in the PETSc documentatio…
179 - [Annual-Meetings](https://gitlab.com/petsc/annual-meetings) contains various documents from the {…
180 - [Datafiles](https://gitlab.com/petsc/datafiles) contains large matrices, meshes, and various othe…
182 - [Tutorials]((https://gitlab.com/petsc/annual-meetings) contains slides from {any}`tutorials`. See…
200 Any new images required must be added to the currently-used branch of this repository.
204 - Whenever possible, use SVG files. SVG is a web-friendly vector format and will be automatically c…
205 - Avoid large files and large numbers of images.
206 - Do not add movies or other non-image files.
210 - Decide where in `doc/images` a new image should go. Use the structure of the `doc/` tree as a gui…
211 - Create a Merge Request to the currently-used branch of the upstream images repository, adding thi…
212 - Once this Merge Request is merged, you may make a MR on the main PETSc Git repository relying on …
220 Simply add a logically-numbered new version of the image.
223 add it to the top-level list of files to delete in the images repository.
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
242 It is stored in [Annual-Meetings](https://gitlab.com/petsc/annual-meetings) repository and linked f…
244 The files are all in the public directory of the repository so that the `.gitlab-ci.yml` file for t…
245 automatically displays all the files at https://petsc.gitlab.io/annual-meetings. Thus, all one need…
246 [Annual-Meetings](https://gitlab.com/petsc/annual-meetings) and provide appropriate links within th…
256 The files are all in the public directory of the repository so that the `.gitlab-ci.yml` file for t…
265 The manual pages and C2HTML-generated file as built in a process described below using the document…
268 - [Sowing](https://bitbucket.org/petsc/pkg-sowing): Developed by Bill Gropp, this produces the PETS…
269 - [C2html](https://gitlab.com/petsc/pkg-c2html): This generates the HTML versions of all the source…
271 Sowing and C2html are build tools that do not use the compilers specified to PETSc's `configure`, a…
272 need to work in cross-compilation environments. Thus, they default to using `gcc`, `g++`, and `flex…
273 the user's environment (or `configure` options like `--download-sowing-cxx`). Microsoft Windows use…
274 etc., from Cygwin in order to be able to build the documentation.
279 …-footnote]: The extensions's [development branch](https://github.com/mcmtroffaes/sphinxcontrib-bib…
281 [^svg-footnote]: `rsvg-convert` is installable with your package manager, e.g., `librsvg2-bin` on D…
283 [^maintainer-fast-image-footnote]: Maintainers may directly push commits.