Better integrate man pages into Sphinx
It would be better if the man pages were more natively integrated with Sphinx, producing input files that Sphinx can use in its normal way. It would also remove a great deal of brittle custom logic which is used to integrate the classic system of man pages into the Sphinx build.
There have been various proposals about how to do this, but most so far have involved leaving Sowing-formatted information inline with the source (as these are also used to generate Fortran stubs).
One could fairly easily add a new output format to Sowing to produce .rst
(or .md
, see #1011) output. The Sowing source is well organized and already has the details for each output format nicely factored into files (http://wgropp.cs.illinois.edu/projects/software/sowing/doctext/node28.htm#Node28). However, there is a great deal of custom, html-specific post-processing performed on the man pages after they are generated.
This would help accomplish goals like things like
- letting the website search (#328 (closed)) cover the man pages and
- more easily supporting links from the man pages back to the other documentation (#1014)
Note: SLEPc uses some of our "classic" docs tools, so be aware of breaking their build.