Hi Jeff,
It sounds like music to me. The OpenMPI doc needs some sort of boost and
Sphinx is the ideal package for this.
Cheers,
Luis Cebamanos
On 16/11/2020 21:02, Jeff Squyres (jsquyres) via devel wrote:
> 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?
>
The University of Edinburgh is a charitable body, registered in Scotland, with
registration number SC005336.
