Question about this. Do we have any literalincludes that are indexed by line number? I thought I have done this, and your discussion below makes me realize that this is fragile. There is still some fragility with function names, but that ostensibly can be caught by the mechanism itself. Thanks, Matt On Fri, Nov 5, 2021 at 4:01 AM Patrick Sanan <[email protected]> wrote:
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-gui...
-- What most experimenters take for granted before they begin their experiments is infinitely more interesting than any results to which their experiments lead. -- Norbert Wiener https://www.cse.buffalo.edu/~knepley/ <http://www.cse.buffalo.edu/~knepley/>