<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">Am Mo., 17. Juni 2019 um 21:27 Uhr schrieb Lawrence Mitchell <<a href="mailto:wence@gmx.li">wence@gmx.li</a>>:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><br>
<br>
> On 17 Jun 2019, at 19:50, Jed Brown via petsc-dev <<a href="mailto:petsc-dev@mcs.anl.gov" target="_blank">petsc-dev@mcs.anl.gov</a>> wrote:<br>
<br>
[...]<br>
> <br>
> As for strategy, we have these primary forms of documentation:<br>
> <br>
> * Users Manual<br>
> <br>
>  A lot of value here is in cross-references between the manual and man<br>
>  pages.  PETSc has a special pass where it creates links from to all<br>
>  the man pages every time a keyword appears, including in listings.<br>
>  I'd rather not be verbose about it in rst source as in<br>
>  :c:func:`~.PetscScalar`.  <br>
<br>
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.<br>
<br>
>  Also, the Firedrake manual (and I think<br>
>  Sphinx as a whole) doesn't hyperlink keywords appearing in source.<br>
>  So, for example, there is no link from CircleManifoldMesh to a man<br>
>  page.<br>
> <br>
>  <a href="https://www.firedrakeproject.org/extruded-meshes.html#generating-extruded-meshes-in-firedrake" rel="noreferrer" target="_blank">https://www.firedrakeproject.org/extruded-meshes.html#generating-extruded-meshes-in-firedrake</a><br>
<br>
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.<br></blockquote><div>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</div><div>1. Use pandoc to convert (a section of) the dev manual to the new .rst format</div><div>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)</div><div>3. Generate an example of what the new html dev manual would like</div><div>This would</div><div>- probably reveal some gotchas about this approach</div><div>- be a good step along the way to a useful first result, which is the manual and dev manual on the web</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">
> * Manual pages<br>
> <br>
>  I need to learn a bit more about the numpydoc and breathe<br>
>  implementations to be able to write a Sowing parser for it.<br>
<br>
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 <br>
<br>
>> For instance, can we start by just generating stub .rst-formatted man<br>
>> pages, which include a link to the existing man pages?<br>
> <br>
> I guess, but all the value is in cross-references.  Also, I don't care<br>
> to have an rst-formatted representation appear in a file.<br>
<br>
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.<br>
<br>
Lawrence<br>
<br></blockquote><div><br></div></div></div>