Patrick Sanan <[email protected]> writes: >> Am 26.05.2021 um 18:39 schrieb Jed Brown <[email protected]>: >> >> Patrick Sanan <[email protected] <mailto:[email protected]>> >> writes: >> >>>> Am 25.05.2021 um 22:58 schrieb Barry Smith <[email protected]>: >>>> >>>> >>>> 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
