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

[Matthew Knepley]

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 <patrick.sanan at gmail.com>
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-guidelines
>
>

-- 
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/>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20211105/dc2a2bc5/attachment.html>