[petsc-dev] User(s) manual sections field in manual pages?

[Jed Brown]

Lawrence Mitchell <wence at gmx.li> writes:

>> On 17 Jun 2019, at 19:50, Jed Brown via petsc-dev <petsc-dev at mcs.anl.gov> wrote:
>
> [...]
>> 
>> As for strategy, we have these primary forms of documentation:
>> 
>> * Users Manual
>> 
>>  A lot of value here is in cross-references between the manual and man
>>  pages.  PETSc has a special pass where it creates links from to all
>>  the man pages every time a keyword appears, including in listings.
>>  I'd rather not be verbose about it in rst source as in
>>  :c:func:`~.PetscScalar`.  
>
> Yes, this is a disadvantage of OOTB sphinx (unless we've misconfigured
> it). You have to explicitly mark up the links in the long-form
> documentation that you would like to link. I guess we could do it
> after the fact, but have not done so. As a result, we're rather
> inconsistent about it. This is "fine" if you're reading the whole
> manual with a Python terminal up and running to check docstrings, but
> hardly seamless.

The noisiness of the native RST source representation is also pretty
gross in my opinion.

>>  Also, the Firedrake manual (and I think
>>  Sphinx as a whole) doesn't hyperlink keywords appearing in source.
>>  So, for example, there is no link from CircleManifoldMesh to a man
>>  page.
>> 
>>  https://www.firedrakeproject.org/extruded-meshes.html#generating-extruded-meshes-in-firedrake
>
> It ought, I suppose, be possible to write a plugin that adds links automagically to all keywords in formatted source, but I don't know the details of how these are written.

Right, we have to learn how to add such things.  If you know where to
look, it would be helpful.

>> * Manual pages
>> 
>>  I need to learn a bit more about the numpydoc and breathe
>>  implementations to be able to write a Sowing parser for it.
>
> Would this be changing the format for man page docs to numpydoc? I don't know enough about the current setup one-way or another to know if 

I guess that could be considered, but I meant parsing Sowing to talk to
Sphinx in the same way that numpydoc parses its format for Sphinx.  I
haven't found a nice tutorial on this so I figured I would work it out
from the implementations of numpydoc/breathe.

>>> For instance, can we start by just generating stub .rst-formatted man
>>> pages, which include a link to the existing man pages?
>> 
>> I guess, but all the value is in cross-references.  Also, I don't care
>> to have an rst-formatted representation appear in a file.
>
> This is certainly a disadvantage of our approach: docstrings as formatted in the python repl are ugly if they contain much linking (and/or maths). Having a setup that minimises the amount of noise in the text format is probably preferable.

I care about the source format too because that's what people need to
edit.