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

[Lawrence Mitchell]

> On 5 Nov 2021, at 15:25, Patrick Sanan <patrick.sanan at gmail.com> wrote:
> 
> 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 PetscError(
> :end-at: PetscFunctionReturn(0)
> :append: }

FWIW, this feels a bit like trying to reinvent WEB.

Doing actual literate documentation of key tutorial programs would be a nice way of doing this, but I realise that's a lot more effort.

Lawrence