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 <devel@lists.open-mpi.org <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 <https://docs.open-mpi.org> (hosted by readthedocs.io <http://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 <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 <http://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/ <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 <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 and >=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 bunch of "TODO" items in the HTML docs. We merged "early" so that we could get wider testing of the configury, and we need people to stop updating the old docs. It was time to switch everyone over to the new system, and move forward from there. Please, please, please make edits to the docs. Using RST makes the docs pretty darn easy. -- Jeff Squyres jsquy...@cisco.com <mailto:jsquy...@cisco.com> -- Josh Hursey IBM Spectrum MPI Developer
