[petsc-dev] links from manual pages to users manual

[Jed Brown]

Patrick Sanan <patrick.sanan at gmail.com> writes:

>> Am 26.05.2021 um 18:39 schrieb Jed Brown <jed at jedbrown.org>:
>> 
>> Patrick Sanan <patrick.sanan at gmail.com <mailto:patrick.sanan at gmail.com>> writes:
>> 
>>>> Am 25.05.2021 um 22:58 schrieb Barry Smith <bsmith at petsc.dev>:
>>>> 
>>>> 
>>>>  Now that the users manual is html and we can properly link into it, it would be great to have links from the manual pages to appropriate locations in the users manual. For example SNESSetFunction.html would have a link to the generated Spinx location where SNESSetFunction is discussed.
>>>> 
>>>>  How do we go about doing this? 
>>>> 
>>>>  Not only is this useful for users but when developers are fixing/improving a manual page it would be nice if they had a way to jump directly to the appropriate place in the xxx.rst that that discusses the manual page to check that that material is also up-to-date and correct. So I guess we need a way to link to the correct place in the .rst and the generated .html
>>>> 
>>> This all depends on which approach we take to make the man pages better integrated. There are competing requirements so I think it'll have to be hashed out to find the correct compromise
>>> 
>>> - we need to leave things for Sowing to generate Fortran stubs
>>> - we want to be able to write the man pages as .rst, like the rest of the Sphinx docs
>> 
>> Or Markdown; see recent activity in this issue.
>> 
>> https://github.com/executablebooks/MyST-Parser/issues/228#issuecomment-848505703 <https://github.com/executablebooks/MyST-Parser/issues/228#issuecomment-848505703>
>
> This is cool to know about - if I'm reading this correctly it's not ready for us to immediately adopt, but  I don't think you'll find many who like RST more than Markdown, so if there's a good chance to switch from RST to MyST at some point, I think it makes sense (say if there's a robust automatic rst-to-myst convertor, which seems to almost exist <https://github.com/executablebooks/rst-to-myst> now). My hesitancy to do it now comes from RST's privileged status as a the dumb default which you can google about,  and not wanting to incrementally introduce MyST because I fear that'll make things worse for people wanting to edit (two new things to learn, can't copy-paste things between the two).

I think it's ready for use (we use it in crikit.science) and I intend to convert libCEED using rst-to-myst as soon as this issue is resolved (or one of us can implement it):

https://github.com/executablebooks/rst-to-myst/issues/13

We have lots of equations and clean syntax is a huge selling point of MyST. It will also save us some hackery copying files around (which breaks the edit-this-page links).

https://myst-parser.readthedocs.io/en/latest/using/howto.html#include-a-file-from-outside-the-docs-folder-like-readme-md