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

[Patrick Sanan]

Am Mo., 17. Juni 2019 um 21:27 Uhr schrieb Lawrence Mitchell <wence at gmx.li>:

>
>
> > 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.
>
> >  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.
>
Sounds like Jed's suggesting that this could be done with a script similar
to the one that exists now for the manual. How about
1. Use pandoc to convert (a section of) the dev manual to the new .rst
format
2. Modify the existing script to add links from (temporary copies of) the
new .rst to the existing man pages (still using the existing htmlmap file)
3. Generate an example of what the new html dev manual would like
This would
- probably reveal some gotchas about this approach
- be a good step along the way to a useful first result, which is the
manual and dev manual on the web

> * 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
>
> >> 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.
>
> Lawrence
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20190617/4a742cab/attachment.html>