Continued docs updates

.readthedocs.yaml

@@ -8,3 +8,4 @@ version: 2
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
+  fail_on_warning: true

docs/Makefile.am

@@ -785,6 +785,40 @@ OSHMEM_MAN1_BUILT = $(OSHMEM_MAN1:%.1=$(MAN_OUTDIR)/%.1)
 OSHMEM_MAN3_RST = $(OSHMEM_MAN3:%.3=man-oshmem/man3/%.3.rst)
 OSHMEM_MAN3_BUILT = $(OSHMEM_MAN3:%.3=$(MAN_OUTDIR)/%.3)
 
+EXTRA_DIST += \
+        $(OMPI_MAN1_BUILT) \
+        $(OMPI_MAN3_BUILT) \
+        $(OMPI_MAN5_BUILT) \
+        $(OSHMEM_MAN1_BUILT) \
+        $(OSHMEM_MAN3_BUILT)
+
+###########################################################################
+
+# These files are not generated by Sphinx (they are redirects to
+# Sphinx-generated man pages).
+OMPI_MAN1_REDIRECTS = \
+        man-openmpi/man1/mpicc.1 \
+        man-openmpi/man1/mpicxx.1 \
+        man-openmpi/man1/mpic++.1 \
+        man-openmpi/man1/mpifort.1 \
+        man-openmpi/man1/mpif77.1 \
+        man-openmpi/man1/mpif90.1 \
+        man-openmpi/man1/mpijavac.1
+
+OSHMEM_MAN1_REDIRECTS = \
+        man-openshmem/man1/oshcc.1 \
+        man-openshmem/man1/oshcxx.1 \
+        man-openshmem/man1/oshc++.1 \
+        man-openshmem/man1/oshfort.1 \
+        man-openshmem/man1/shmemcc.1 \
+        man-openshmem/man1/shmemcxx.1 \
+        man-openshmem/man1/shmemc++.1 \
+        man-openshmem/man1/shmemfort.1
+
+EXTRA_DIST += \
+        $(OMPI_MAN1_REDIRECTS) \
+        $(OSHMEM_MAN1_REDIRECTS)
+
 ###########################################################################
 if OPAL_BUILD_DOCS
 
@@ -840,32 +874,19 @@ endif OPAL_BUILD_DOCS
 ###########################################################################
 if OPAL_INSTALL_DOCS
 
-dist_man1_MANS = \
+man1_MANS = \
         $(OMPI_MAN1_BUILT) \
-        man-openmpi/man1/mpicc.1 \
-        man-openmpi/man1/mpicxx.1 \
-        man-openmpi/man1/mpic++.1 \
-        man-openmpi/man1/mpifort.1 \
-        man-openmpi/man1/mpif77.1 \
-        man-openmpi/man1/mpif90.1 \
-        man-openmpi/man1/mpijavac.1
+        $(OMPI_MAN1_REDIRECTS)
 
-dist_man3_MANS = $(OMPI_MAN3_BUILT)
-dist_man5_MANS = $(OMPI_MAN5_BUILT)
+man3_MANS = $(OMPI_MAN3_BUILT)
+man5_MANS = $(OMPI_MAN5_BUILT)
 
 if PROJECT_OSHMEM
-dist_man1_MANS += \
+man1_MANS += \
         $(OSHMEM_MAN1_BUILT) \
-        man-openshmem/man1/oshcc.1 \
-        man-openshmem/man1/oshcxx.1 \
-        man-openshmem/man1/oshc++.1 \
-        man-openshmem/man1/oshfort.1 \
-        man-openshmem/man1/shmemcc.1 \
-        man-openshmem/man1/shmemcxx.1 \
-        man-openshmem/man1/shmemc++.1 \
-        man-openshmem/man1/shmemfort.1
+        $(OSHMEM_MAN1_REDIRECTS)
 
-dist_man3_MANS += $(OSHMEM_MAN3_BUILT)
+man3_MANS += $(OSHMEM_MAN3_BUILT)
 endif
 
 endif OPAL_INSTALL_DOCS

docs/conf.py

@@ -31,7 +31,8 @@
 ompi_data = dict()
 for ompi_line in ompi_lines:
     if '#' in ompi_line:
-        ompi_line, _ = ompi_line.split("#")
+        parts = ompi_line.split("#")
+        ompi_line = parts[0]
     ompi_line = ompi_line.strip()
 
     if '=' not in ompi_line:
@@ -40,11 +41,63 @@
     ompi_key, ompi_val = ompi_line.split("=")
     ompi_data[ompi_key.strip()] = ompi_val.strip()
 
-# "release" is a sphinx config variable -- assign it to the computed
-# Open MPI version number.
-series = f"{ompi_data['major']}.{ompi_data['minor']}.x"
-release = f"{ompi_data['major']}.{ompi_data['minor']}.{ompi_data['release']}{ompi_data['greek']}"
+ompi_series = f"v{ompi_data['major']}.{ompi_data['minor']}.x"
+ompi_ver = f"v{ompi_data['major']}.{ompi_data['minor']}.{ompi_data['release']}{ompi_data['greek']}"
 
+# "release" is a sphinx config variable: assign it to the computed
+# Open MPI version number.  The ompi_ver string begins with a "v"; the
+# Sphinx release variable should not include this prefix "v".
+release = ompi_ver[1:]
+
+# If we are building in a ReadTheDocs.io environment, there will be a
+# READTHEDOCS environment variables that tell us what version to use.
+# Relevant RTD env variables (documented
+# https://docs.readthedocs.io/en/stable/builds.html#build-environment):
+#
+# - READTHEDOCS: will be "True"
+# - READTHEDOCS_VERSION: The RTD slug of the version which is being
+#   built (e.g., "latest")
+# - READTHEDOCS_VERSION_NAME: Corresponding version name as displayed
+#   in RTD's version switch menu (e.g., "stable")
+# - READTHEDOCS_VERSION_TYPE: Type of the event triggering the build
+#   (e.g., "branch", "tag", "external" (for PRs), or "unknown").
+#
+# If we're building in an RTD environment for a tag or external (i.e.,
+# PR), use the RTD version -- not what we just read from the VERSIONS
+# file.
+import os
+key = 'READTHEDOCS'
+if key in os.environ and os.environ[key] == 'True':
+    print("OMPI: found ReadTheDocs build environment")
+
+    rtd_v = os.environ['READTHEDOCS_VERSION']
+    if os.environ['READTHEDOCS_VERSION_TYPE'] == 'external':
+        # Make "release" be shorter than the full "ompi_ver" value.
+        release = f'PR #{rtd_v}'
+        ompi_ver += f' (Github PR #{rtd_v})'
+    else:
+        ompi_ver = rtd_v
+
+        # The "release" Sphinx variable is supposed to be expressed as
+        # a simple value, such as "A.B.C[rcX]" (without a leading
+        # "v").  The ompi_ver value will be one of two things:
+        #
+        # - a git branch name (of the form "vA.B.x")
+        # - a git tag (of the form "A.B.C[rcX]")
+        #
+        # If there's a leading "v", we need to strip it.
+        release = ompi_ver
+        if ompi_ver[0] == 'v':
+            release = ompi_ver[1:]
+
+    # Override the branch names "master" and "main" (that would have
+    # come from the ReadTheDocs version slug) to be "head of
+    # development".
+    if release == 'main' or release == 'master':
+        ompi_ver = 'head of development'
+
+    print(f"OMPI: release = {release}")
+    print(f"OMPI: ompi_ver = {ompi_ver}")
 
 # -- General configuration ---------------------------------------------------
 
@@ -124,6 +177,6 @@ def _doit(topdir):
 .. |rarrow| unicode:: U+02192 .. Right arrow
 
 .. |year| replace:: {year}
-.. |ompi_ver| replace:: v{release}
-.. |ompi_series| replace:: v{series}
+.. |ompi_ver| replace:: {ompi_ver}
+.. |ompi_series| replace:: {ompi_series}
 """

docs/faq/debugging.rst

@@ -538,7 +538,7 @@ There are two cases:
    <https://valgrind.org/docs/valgrind2007.pdf>`_.
    For an evaluation of various internal implementation alternatives of Shadow Memory, please see
    `Building Workload Characterization Tools with Valgrind
-   <https://www.valgrind.org/njn/pubs/shadow-memory2007-talk.ppt>`_.
+   <https://valgrind.org/docs/iiswc2006.pdf>`_.
 
 
 Further information and performance data with the NAS Parallel

docs/faq/fault-tolerance.rst

@@ -1,18 +1,14 @@
 Fault Tolerance
 ===============
 
-.. TODO Hello world
-
-/////////////////////////////////////////////////////////////////////////
-
 What is "fault tolerance"?
 --------------------------
 
 The phrase "fault tolerance" means many things to many
-people.  Typical definitions range from user processes dumping vital
-state to disk periodically to checkpoint/restart of running processes
-to elaborate recreate-process-state-from-incremental-pieces schemes to
-... (you get the idea).
+people.  Typical definitions include user processes dumping vital
+state to disk periodically, checkpoint/restart of running processes,
+elaborate recreate-process-state-from-incremental-pieces schemes,
+and many others.
 
 In the scope of Open MPI, we typically define "fault tolerance" to
 mean the ability to recover from one or more component failures in a
@@ -99,7 +95,7 @@ links below:
 * `MPI Forum's Fault Tolerance Working Group <https://github.com/mpiwg-ft/ft-issues/wiki>`_
 * Fault Tolerant MPI Prototype:
     * `Development / code <https://bitbucket.org/icldistcomp/ulfm2>`_
-    * `Information and support <http://fault-tolerance.org/>`_
+    * `Information and support <https://fault-tolerance.org/>`_
 
 Support for other types of resilience (e.g., :ref:`data reliability <faq-ft-data-reliability-label>`,
 checkpoint) has been deprecated over the years

docs/faq/running-mpi-apps.rst

@@ -762,9 +762,12 @@ Several notable options are:
 How do I use the ``--hostfile`` option to ``mpirun``?
 -----------------------------------------------------
 
-.. error:: TODO For cross reference, this is the PRRTE man page section
-           about ``--hostfile``:
-           https://github.com/openpmix/prrte/blame/master/src/tools/prte/prte-map.1.md#L236
+.. error:: TODO For cross reference, this is the PRRTE man page
+           section about ``--hostfile``:
+           https://github.com/openpmix/prrte/blob/b70a6f1a8d424e396c40c999a656b04e76cc0f91/src/tools/prte/prte-map.1.md?plain=1#L236
+           A subsequent commit removed this markdown file; the commit
+           message refers to moving the markdown file to another git
+           repo, but I didn't chase down where it went.
 
 The ``--hostfile`` option to ``mpirun`` takes a filename that lists
 hosts on which to launch MPI processes.

docs/faq/sysadmin.rst

@@ -220,7 +220,7 @@ to tweak are:
      parameters in *levels*, as defined by the MPI_T interface from
      the MPI standard.  You will need to specify ``--level 9`` (or
      ``--all``) to show *all* MCA parameters.  `See this blog entry
-     <http://blogs.cisco.com/performance/open-mpi-and-the-mpi-3-mpi_t-interface>`_
+     <https://blogs.cisco.com/performance/open-mpi-and-the-mpi-3-mpi_t-interface>`_
      for further information.
 
   .. code-block:: sh

docs/features/ulfm.rst

@@ -23,7 +23,7 @@ execution environment up and running.
 This implementation produces the three supplementary error codes and
 five supplementary interfaces defined in the communicator section of
 the `ULFM chapter
-<http://fault-tolerance.org/wp-content/uploads/2012/10/20170221-ft.pdf>`_
+<https://fault-tolerance.org/wp-content/uploads/2012/10/20170221-ft.pdf>`_
 standard draft document.
 
 * ``MPIX_ERR_PROC_FAILED`` when a process failure prevents the
@@ -95,7 +95,7 @@ please use:
     J. Dongarra: Post-failure recovery of MPI communication
     capability: Design and rationale. IJHPCA 27(3): 244-254 (2013).*
 
-Available from: http://journals.sagepub.com/doi/10.1177/1094342013488238.
+Available from: https://journals.sagepub.com/doi/10.1177/1094342013488238.
 
 Building ULFM support in Open MPI
 ---------------------------------
@@ -522,9 +522,8 @@ [email protected]!).  Visit these pages to subscribe to the
 lists: https://groups.google.com/forum/#!forum/ulfm
 
 When submitting questions and problems, be sure to include as much
-extra information as possible.  This web page details all the
-information that we request in order to provide assistance:
-http://www.open-mpi.org/community/help/
+extra information as possible.  See the :doc:`Getting help
+</getting-help>` section for more details.
 
 Thanks for your time.
 

docs/index.rst

@@ -1,8 +1,8 @@
 .. image:: openmpi_logo.png
    :align: right
 
-Open MPI
-========
+Open MPI |ompi_ver|
+===================
 
 `The Open MPI Project <https://www.open-mpi.org/>`_ is an open source
 implementation of the `Message Passing Interface (MPI) specification
@@ -14,11 +14,10 @@ order to build the best MPI library available.  Open MPI offers
 advantages for system and software vendors, application developers and
 computer science researchers.
 
-Other documentation
-===================
+Documentation locations
+=======================
 
-Documentation for other versions of Open can be found in the following
-locations:
+Documentation for Open can be found in the following locations:
 
 .. list-table::
    :header-rows: 1
@@ -28,7 +27,8 @@ locations:
 
    * - v5.0.0 and later
      - Open MPI documentation has consolidated and moved to
-       ReadTheDocs.io.
+
+       https://docs.open-mpi.org/.
 
        This particular documentation is for |ompi_ver|; use the
        selector in the