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

[Patrick Sanan]

Am Fr., 5. Nov. 2021 um 19:18 Uhr schrieb Lawrence Mitchell <wence at gmx.li>:

>
> > 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.
>
I don't know what WEB is, but if you're saying that this is kinda clunky,
yes it definitely is - my only contention is that it's better than
copy-pasting code and output.  I'm not sure if there's an easier and/or
better way with Sphinx.

>
> 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.
>
This is still a hope/plan to go into doc/tutorials - follow the deal.ii
model for a small number of key examples. Matt has done a couple of pages
there already, in this direction.

Lawrence
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20211106/5cc48754/attachment.html>