[petsc-dev] [DocTip!] #2: Aiming for self-updating docs

[Patrick Sanan]

A big problem with documentation is that it goes out of date. This quickly
takes something that was useful to something which is actually harmful.
Showing the user things that don't work exactly as described is worse than
showing them nothing.

So, it's good to aspire to writing docs in as future-proof a way as
possible, especially given the broad scope and rapid rate of change in
PETSc.

One step in this direction that we use currently is to avoid including
explicit code blocks and output [2], but rather excerpt from the src/ tree
for both code and the same output used for the test suite.

An example of where this is done is in the classic "hand-on" tutorials [1]:
these used to be part of an HTML page with the output inline, but now the
source uses syntax like this:

.. literalinclude:: /../src/ksp/ksp/tutorials/output/ex50_tut_3.out
:language: none

This isn't a bulletproof approach yet - the output can still be out of
date, but good enough to pass the test suite (though that can at least be
bulk-updated with a single command), and the input command is still
literally included. Still, it reduces the maintenance burden of
documentation and reduces the chance of confusing the reader with stale
information.

[1]: https://petsc.org/release/tutorials/handson/
[2]:
https://petsc.org/release/developers/documentation/#sphinx-documentation-guidelines
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20211105/5ed09a71/attachment.html>