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 <knep...@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.sa...@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/> >