Over the past few months, I've been musing about Open MPI's documentation.
Short version
=============
For v5.0.0, I propose:
1. Move the README to reStructured Text ("RST"), and split it up into multiple
pages.
* Use Sphinx (https://www.sphinx-doc.org/en/master/) to render this RST into
HTML.
* Host the HTML on readthedocs.io.
2. Also (eventually) move the Open MPI man pages into this RST tree.
3. Also (eventually) move the FAQ into this RST tree.
This would bring all 3 sources of our docs together into a single, cohesive set.
I took a swipe at #1 -- see
https://aws.open-mpi.org/~jsquyres/rst-docs-unofficial/.
--> This link will likely only work for some amount of time in Nov 2020.
I also propose that we RST-ize the v4.1 README into RST and also host it on
readthedocs.io.
More detail
===========
Our current docs are kind of a mess.
1. The README has a *ton* of information in it, but it's a giant wall of text,
and I'll bet very few people actually read it.
2. The FAQ also has a ton of information, but it suffers from version skew, and
is difficult to maintain.
3. The man pages have also bit rotted a bit, but there's a ton of good info in
there, too.
The goal would be to bring all 3 of these together into a cohesive set of docs
in an aesthetically pleasing, web-friendly, Google-friendly, and
maintainer-friendly way.
The Sphinx package seems to do this pretty well:
- Everything is written in RST and/or Markdown (although RST is more
feature-full than Markdown).
- You can render to static HTML to a local directory and then browse it with
your local web browser
- Free hosting of open source Sphinx-generated documentation is provided on
readthedocs.io
- readthedocs.io also offers GitHub webhooks to automatically re-render if the
docs ever change in your GitHub repo (sweet!)
We can either include the Sphinx-generated HTML on the main Open MPI web site
or just use the free hosting on readthedocs.io (I'm leaning towards using their
hosting, but still need to understand that a bit more). One of the advantages
of readthedocs.io-hosted docs is that they are versioned. This would seem to
solve the version-skew problems with our current FAQ.
The FAQ will require hand-conversion to RST. I'll do that, but it'll take me
some time to get it done.
As some of you may know, some students have taken a swipe at Markdown-izing the
man pages (we opted for Markdown before we started looking at Sphinx /
readthedocs.io). By the end of their semester (i.e., within a week or three),
they'll have a few dozen of the man pages converted to Markdown. They also
have a Python script to do most of the conversion nroff->markdown. So even if
they don't finish Markdown-izing all the man pages, it's possible for someone
in the community to finish that effort.
These man pages could be imported into a Sphinx project as Markdown, or they
could be converted to RST (MD to RST is a fairly straightforward conversion).
I think that if we actually manage to convert 3 sources into a single, cohesive
RST tree, that will be a huge win for making the docs much more:
- readable by end users (smaller, individual pages with docs content)
- Google friendly
- maintainable by the community
However, all of this is on master (i.e., what will become v5.0.0). Given that
v5.0.0 may still take some time to get released. I think it might be worthwhile
to:
1. Basically repeat the RST-ization of the README on the v4.1.x branch (which
is relatively straightforward)
2. Publish the this RST-ized tree out to readthedocs.io
3. NOT convert the v4.1.x man pages or FAQ (which would be a ton a work) --
i.e., leave the FAQ and man pages as they are for v4.1.x
This will at least improve the README content for v4.1.x, and increase the
Google-ability of our documentation content. Over time -- i.e., when v5.0.0 is
released -- we'll basically add the v5.0.0 version at readthedocs.io and
include the FAQ and man pages in the content.
Thoughts?
--
Jeff Squyres
jsquy...@cisco.com
