On 5 Nov 2021, at 15:25, Patrick Sanan <[email protected]> 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