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

[Patrick Sanan]

Good question. We don't have any that start at specific line numbers,
currently, as it is indeed too brittle - I suspect I removed some that were
there at one point.

The inclusions essentially all use :start-at: to specify a line to match.
Ideally you'd also use :end-at: to specify where to stop, but some short
snippets do instead specify a number of lines. Note that a practically
handy option is :append:, as in this example where you are trying to
excerpt the function PetscError(), and you can match on the
PetscFunctionReturn(0) and then re-add the closing brace.

.. literalinclude:: /../src/sys/error/err.c
   :start-at: PetscErrorCode
<https://petsc.org/release/docs/manualpages/Sys/PetscErrorCode.html#PetscErrorCode>
PetscError <https://petsc.org/release/docs/manualpages/Sys/PetscError.html#PetscError>(
   :end-at: PetscFunctionReturn
<https://petsc.org/release/docs/manualpages/Sys/PetscFunctionReturn.html#PetscFunctionReturn>(0)
   :append: }




Am Fr., 5. Nov. 2021 um 15:00 Uhr schrieb Matthew Knepley <knepley at gmail.com
>:

> 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/3969bfbe/attachment-0001.html>