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

[Matthew Knepley]

On Sat, Nov 6, 2021 at 10:34 AM Patrick Sanan <patrick.sanan at gmail.com>
wrote:

>
>
> 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.
>

WEB was the futuristic documentation idea of Don Knuth.

  Thanks,

     Matt


>
>> 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
>
>

-- 
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/20211106/ef0f1bb2/attachment-0001.html>