Re: [OMPI devel] First Open MPI v5.0.x docs have been merged

[Josh Hursey via devel]

This is an awesome advancement in our documentation process. Thank you to 
everyone that worked so hard on this project to bring it to fruition! 

On Mon, Mar 7, 2022 at 9:25 PM Jeff Squyres (jsquyres) via devel 
mailto:devel@lists.open-mpi.org> > wrote:
Our first cut of the ReStructured Text (RST)/Sphinx HTML docs and man pages 
have been committed to master -- woo hoo!

There's a few things the developer community needs to know.

Web site

The docs are now live on https://docs.open-mpi.org  
(hosted by readthedocs.io  ).

Right now, there's just "master" docs available (i.e., the docs from the git 
branch named "master").  If you merge a change to the docs on master, the docs 
on the web site will automatically update.

Since it's just master so far, we're not advertising these docs yet.  Indeed, 
there's a lot of 5.0.0-specific content on these docs -- we don't really want 
to send 4.1.x users to these docs yet.

Eventually, the web site will have the 5.0.0 (and 5.0.1 and 5.0.2 and ...) docs 
up there, too.  But for now: just master.

Git sources

The source for the docs live in the "docs/" directory on master.  None of the 
generated HTML or nroff files are in the repository; only the RST source.

If you get a git clone, you need to have Sphinx (the tool we use to render the 
docs into HTML and nroff) installed and in your environment before running 
configure if you want to build the HTML docs and man pages.  See 
https://docs.open-mpi.org/en/master/developers/sphinx.html 
  for details.

We'll going to let the whole new docs system soak for a little while before 
cherry picking to the v5.0.x branch.

Updating the docs: pull requests

PLEASE MAKE PULL REQUESTS TO UPDATE THE DOCS!! 

You can just edit the RST files under docs/, just like any other files.

In the docs/ directory, you can just "make".  Assuming you had Sphinx in your 
environment before you ran configure, it will build the docs right there:
*   The HTML pages can be found under "docs/_build/html/index.html".  You 
can just open that locally in a web browser to see your changes.
*   The man pages are in "docs/_build/man".  You can just use "man 
docs/_build/man/MPI_Send.3" (for example) to view them.
When you create a pull request, the docs on your PR will be rendered to a 
temporary/PR-specific location on readthedocs.io  .  Go 
down to the bottom of the PR and you'll see a CI item for 
"docs/readthedocs.org:ompi".  If you click the "Details" link, it'll take you 
to this PR's build of the docs.

If you introduce any RST/Sphinx warnings or errors in your PR, CI will fail, 
and you will not be able to merge your PR (pro tip: fix the warnings / errors, 
and then you'll be able to merge your PR).

Distribution tarballs

Similar to other tools that we Open MPI developers use, end users do NOT need 
to have Sphinx installed.  Official Open MPI tarballs will include the 
pre-built HTML docs and man pages.

When users install from an Open MPI tarball, the man pages will be installed as 
usual.

The HTML docs are not​ installed, but users can view them locally in 
docs/_build/index.html with a local web browser (e.g., if they're at a facility 
that has restricted access to the internet, and they can't reach 
https://docs.open-mpi.org/  ).

ReStructured Text? What the heck is that?

All the new docs -- HTML pages and man pages -- are written in ReStructured 
Text (RST).  Think of RST as Markdown on steroids.  It's a little more 
complicated than Markdown, but not much.  It's much more powerful than 
Markdown, though.

See https://docs.open-mpi.org/en/master/developers/rst-for-markdown-expats.html 
  
for a quick intro to Open MPI's use of RST.

New configury

I tested all the configury and build stuff as best as I could, but now that 
this is on master and open to a wider audience, we'll likely shake out a few 
more bugs.  Please bear with us; we'll get the bugs fixed as soon as possible.

As mentioned above, you basically need to have the sphinx-build(1) executable 
in your environment before running configure if you want to build the HTML docs 
and man pages.  If you don't have Sphinx, "make dist" will (intentionally) fail.

Building the docs from a fresh git clone may take 3-5 minutes (there's hundreds 
of man pages -- this is what takes the majority of time).  There's stuff to 
watch as the build progresses.

Sphinx is stateful; subsequent builds only rebuild files that have changed.  If 
nothing has changed, a no-op build only takes a few seconds.


"make clean" will not​ remove the generated docs.  "make maintainer-clean" will 
remove the generated docs (i.e., rm -rf docs/_build).

Pandoc

Pandoc is dead; long live Sphinx!

(we were going to use Pandoc for v5.0.0 docs, but that effort is now dead 

[OMPI devel] First Open MPI v5.0.x docs have been merged

[Jeff Squyres (jsquyres) via devel]

Our first cut of the ReStructured Text (RST)/Sphinx HTML docs and man pages 
have been committed to master -- woo hoo!

There's a few things the developer community needs to know.

Web site

The docs are now live on https://docs.open-mpi.org (hosted by readthedocs.io).

Right now, there's just "master" docs available (i.e., the docs from the git 
branch named "master").  If you merge a change to the docs on master, the docs 
on the web site will automatically update.

Since it's just master so far, we're not advertising these docs yet.  Indeed, 
there's a lot of 5.0.0-specific content on these docs -- we don't really want 
to send 4.1.x users to these docs yet.

Eventually, the web site will have the 5.0.0 (and 5.0.1 and 5.0.2 and ...) docs 
up there, too.  But for now: just master.

Git sources

The source for the docs live in the "docs/" directory on master.  None of the 
generated HTML or nroff files are in the repository; only the RST source.

If you get a git clone, you need to have Sphinx (the tool we use to render the 
docs into HTML and nroff) installed and in your environment before running 
configure if you want to build the HTML docs and man pages.  See 
https://docs.open-mpi.org/en/master/developers/sphinx.html for details.

We'll going to let the whole new docs system soak for a little while before 
cherry picking to the v5.0.x branch.

Updating the docs: pull requests

PLEASE MAKE PULL REQUESTS TO UPDATE THE DOCS!! 

You can just edit the RST files under docs/, just like any other files.

In the docs/ directory, you can just "make".  Assuming you had Sphinx in your 
environment before you ran configure, it will build the docs right there:

  *   The HTML pages can be found under "docs/_build/html/index.html".  You can 
just open that locally in a web browser to see your changes.
  *   The man pages are in "docs/_build/man".  You can just use "man 
docs/_build/man/MPI_Send.3" (for example) to view them.

When you create a pull request, the docs on your PR will be rendered to a 
temporary/PR-specific location on readthedocs.io.  Go down to the bottom of the 
PR and you'll see a CI item for "docs/readthedocs.org:ompi".  If you click the 
"Details" link, it'll take you to this PR's build of the docs.

If you introduce any RST/Sphinx warnings or errors in your PR, CI will fail, 
and you will not be able to merge your PR (pro tip: fix the warnings / errors, 
and then you'll be able to merge your PR).

Distribution tarballs

Similar to other tools that we Open MPI developers use, end users do NOT need 
to have Sphinx installed.  Official Open MPI tarballs will include the 
pre-built HTML docs and man pages.

When users install from an Open MPI tarball, the man pages will be installed as 
usual.

The HTML docs are not​ installed, but users can view them locally in 
docs/_build/index.html with a local web browser (e.g., if they're at a facility 
that has restricted access to the internet, and they can't reach 
https://docs.open-mpi.org/).

ReStructured Text? What the heck is that?

All the new docs -- HTML pages and man pages -- are written in ReStructured 
Text (RST).  Think of RST as Markdown on steroids.  It's a little more 
complicated than Markdown, but not much.  It's much more powerful than 
Markdown, though.

See https://docs.open-mpi.org/en/master/developers/rst-for-markdown-expats.html 
for a quick intro to Open MPI's use of RST.

New configury

I tested all the configury and build stuff as best as I could, but now that 
this is on master and open to a wider audience, we'll likely shake out a few 
more bugs.  Please bear with us; we'll get the bugs fixed as soon as possible.

As mentioned above, you basically need to have the sphinx-build(1) executable 
in your environment before running configure if you want to build the HTML docs 
and man pages.  If you don't have Sphinx, "make dist" will (intentionally) fail.

Building the docs from a fresh git clone may take 3-5 minutes (there's hundreds 
of man pages -- this is what takes the majority of time).  There's stuff to 
watch as the build progresses.

Sphinx is stateful; subsequent builds only rebuild files that have changed.  If 
nothing has changed, a no-op build only takes a few seconds.

"make clean" will not​ remove the generated docs.  "make maintainer-clean" will 
remove the generated docs (i.e., rm -rf docs/_build).

Pandoc

Pandoc is dead; long live Sphinx!

(we were going to use Pandoc for v5.0.0 docs, but that effort is now dead and 
fully replaced with all the RST/Sphinx stuff.  There's no more requirement for 
Pandoc)

What about Open MPI versions prior to v5.0.0?

The existing docs for all prior versions of Open MPI will be preserved.  We'll 
clearly distinguish between the =v5.0 docs.

Stay tuned for more info on this subject.

HTML docs content is not yet complete

The docs have been merged to master intentionally before all the content was 
complete.  There's a LOT of docs there, but you'll also see a "to do" page, and 
a