prterun with personalities documentation

[jjhursey]

@jsquyres and I had a design conversation last week about how to handle documenting prterun vs mpirun with Open MPI personality vs mpirun with MPICH personality vs ...

The goal was to create documentation without introducing too much redundancy. For example, there are some common CLI behaviors between the three man pages (such as mapping/ranking/binding).

Additionally, we need a solution where the need for the documentation building tools (i.e., pandoc or sphinx) is optional. And the documentation building tools are not needed for anyone building from the release tarballs.

We sketched this solution:

• Move from pandoc with Markdown to Sphinx with reStructuredText
  • This provides us a means of using Python to do things like search-and-replace. Specifically could be useful to search and replace prterun with mpirun (Open MPI personality) or something like that in man pages.
  • reStructuredText also allows for including other 'pages' into each other. This may help with controlling common language.
• Create a docs subdirectory. Each branch will have its own versioned form of the docs
  • docs subdirectory will contain broad documentation for that release to be rendered in static HTML
  • docs subdirectory will contain the individual man pages written in reStructuredText then rendered into nroff.
• mpirun documentation
  • PRRTE owns the personalities for different launchers so it is the correct place to also have the versioned documentation for that version of the launcher.
  • mpirun with Open MPI personality will be different than mpirun with MPICH personality. So we need to have two different mpirun man pages and Open MPI and MPICH can pick up the 'right' one.
  • Suffix each man page with their schizo component name. Have PRRTE generate a mpirun-ompi for the Open MPI personality, and a mpirun-mpich for the MPICH personality.
  • Install the core PRRTE launchers (prun and prterun) in the default search path: prte-install/share/man
  • Install other launcher personalities in a non default search path: prte-install/share/man-extra
  • Open MPI will copy their prte-install/share/man-extra/mpirun-ompi from PRRTE to ompi-install/share/man/mpirun. This means that if the user installs Open MPI with an external PRRTE they can copy the man page and put it in a search location specific to Open MPI, and 'man mpirun' does what the user expects.
• Create a make docs target that regenerates the docs that is not triggered by make. When creating the distribution tarball we would include the make docs so that the tarball has the rendered documentation, and thus the end-user doesn't need the documentation build tools.
  • Include man pages and the HTML documentation in the tarball. Note that the HTML is static, so it can be rendered without a webserver - you only need a browser.
• Consider moving to Read the Docs for documentation, similar to the Open MPI effort described in Start using readthedocs.io open-mpi/ompi#8329 since we will have most of the documentation in that form anyway.
• Consider moving some of the man page documentation (e.g., map/bind/rank) to the HTML version and just reference it from the man pages. That should help keep the man pages smaller