docs: slurp PRTE's RST files into mpirun.1

This commit introduce a fundamentally new concept: have configure
search PRRTE for RST files to include in Open MPI's documentation
(regardless of whether we're using the internal/bundled PRRTE or an
external PRRTE).  If we're building against an external PRRTE that is
old enough that it doesn't have any RST files installed, we'll make up
some dummy RST files that basically say "you don't get help/content
here because your PRRTE is too old."

To simplify the configury for this scheme, this commit also makes
another change: the pre-built HTML docs and nroff man pages included
in distribution tarballs are now located at docs/html/ and docs/man/,
respectively (vs. the location where we'll build them:
docs/_build/html/ and docs/_build/man/, respectively).  There are two
cases here:

1. If the user has Sphinx available, we'll build the docs under
   docs/_build/, and install those (effectively ignoring the pre-built
   docs).
2. If the user does not have Sphinx available, we'll just install the
   pre-built docs.

This simplified things like "make clean" and "make distcheck".

Including RST content from PRTE required another major change: when we
build the RST docs in a VPATH scenario, we copy the entire docs/
source tree to the build tree.  This allows us to modify the RST
sources a bit (e.g., to include the PRRTE RST files or generate dummy
PRRTE RST files).

mpirun.1.rst is updated to include the RST content from PRRTE about
CLI options.  More work needs to be done here to remove old,
now-redundant content.

Finally, we also amend the advice to implementors to have Sphinx
installed when building their package so that Open MPI's build system
can properly slurp in their PRRTE's RST docs.

Signed-off-by: Jeff Squyres <[email protected]>

.gitignore

@@ -534,3 +534,12 @@ docs/_templates
 # Common Python virtual environment directory names
 venv
 py??
+
+# Copies of PRRTE RST files (i.e., not source controlled in this tree)
+docs/prrte-rst-content
+docs/schizo-ompi-rst-content
+
+# Copies of the built HTML docs and man pages (for distribution
+# tarballs)
+docs/html
+docs/man

Makefile.ompi-rules

@@ -2,6 +2,7 @@
 # Copyright (c) 2008-2022 Cisco Systems, Inc.  All rights reserved.
 # Copyright (c) 2008      Sun Microsystems, Inc.  All rights reserved.
 # Copyright (c) 2020      Intel, Inc.  All rights reserved.
+# Copyright (c) 2023      Jeffrey M. Squyres.  All rights reserved.
 # $COPYRIGHT$
 #
 # Additional copyrights may follow
@@ -26,6 +27,14 @@ OMPI_V_GEN = $(ompi__v_GEN_$V)
 ompi__v_GEN_ = $(ompi__v_GEN_$AM_DEFAULT_VERBOSITY)
 ompi__v_GEN_0 = @echo "  GENERATE" $@;
 
+OMPI_V_COPYALL = $(ompi__v_COPYALL_$V)
+ompi__v_COPYALL_ = $(ompi__v_COPYALL_$AM_DEFAULT_VERBOSITY)
+ompi__v_COPYALL_0 = @echo "  COPY tree $@";
+
+OMPI_V_SPHINX_COPYRST = $(ompi__v_SPHINX_COPYRST_$V)
+ompi__v_SPHINX_COPYRST_ = $(ompi__v_SPHINX_COPYRST_$AM_DEFAULT_VERBOSITY)
+ompi__v_SPHINX_COPYRST_0 = @echo "  COPY RST source files";
+
 OMPI_V_SPHINX_HTML = $(ompi__v_SPHINX_HTML_$V)
 ompi__v_SPHINX_HTML_ = $(ompi__v_SPHINX_HTML_$AM_DEFAULT_VERBOSITY)
 ompi__v_SPHINX_HTML_0 = @echo "  GENERATE HTML docs";

config/ompi_setup_prrte.m4

@@ -19,6 +19,7 @@ dnl Copyright (c) 2019-2020 Intel, Inc.  All rights reserved.
 dnl Copyright (c) 2020-2022 Amazon.com, Inc. or its affiliates.  All Rights reserved.
 dnl Copyright (c) 2021      Nanook Consulting.  All rights reserved.
 dnl Copyright (c) 2021-2022 IBM Corporation.  All rights reserved.
+dnl Copyright (c) 2023      Jeffrey M. Squyres.  All rights reserved.
 dnl $COPYRIGHT$
 dnl
 dnl Additional copyrights may follow
@@ -35,10 +36,29 @@ dnl
 dnl A Makefile conditional OMPI_WANT_PRRTE will be defined based on the
 dnl results of the build.
 AC_DEFUN([OMPI_SETUP_PRRTE],[
-    OPAL_VAR_SCOPE_PUSH([prrte_setup_internal_happy prrte_setup_external_happy])
+    AC_REQUIRE([AC_PROG_LN_S])
+
+OPAL_VAR_SCOPE_PUSH([prrte_setup_internal_happy prrte_setup_external_happy target_rst_dir])
 
     opal_show_subtitle "Configuring PRRTE"
 
+    # We must have setup Sphinx before invoking this macro (i.e., it
+    # is a programming error -- not a run-time error -- if Sphinx was
+    # not previously setup).  Unfortunately, we can't AC REQUIRE it
+    # because the OAC SETUP SPHINX macro requires parameters.  The
+    # only publicly-visible env variable that OAC SETUP SPHINX sets is
+    # $SPHINX_BUILD -- but it may be empty if sphinx-build
+    # legitimately can't be found.  Sooo... we can't really tell here
+    # if OAC SETUP SPHINX has actually been invoked or not.
+
+    # These are sym links to folders with PRRTE's RST files that we'll
+    # slurp into mpirun.1.rst.  We'll remove these links (or even
+    # accidental full copies) now and replace them with new links to
+    # the PRRTE that we find, below.
+    target_rst_dir="$OMPI_TOP_BUILDDIR/docs"
+    rm -rf "$target_rst_dir/prrte-rst-content"
+    rm -rf "$target_rst_dir/schizo-ompi-rst-content"
+
     OPAL_3RDPARTY_WITH([prrte], [prrte], [package_prrte], [1])
 
     AC_ARG_WITH([prrte-bindir],
@@ -101,12 +121,15 @@ AC_DEFUN([OMPI_SETUP_PRRTE],[
                        [$OMPI_USING_INTERNAL_PRRTE],
                        [Whether or not we are using the internal PRRTE])
 
-    OPAL_SUMMARY_ADD([Miscellaneous], [prrte], [], [$opal_prrte_mode])
+    AC_SUBST(OMPI_PRRTE_RST_CONTENT_DIR)
+    AC_SUBST(OMPI_SCHIZO_OMPI_RST_CONTENT_DIR)
+    AM_CONDITIONAL(OMPI_HAVE_PRRTE_RST, [test $OMPI_HAVE_PRRTE_RST -eq 1])
+
+    OPAL_SUMMARY_ADD([Miscellaneous], [PRRTE], [], [$opal_prrte_mode])
 
     OPAL_VAR_SCOPE_POP
 ])
 
-
 dnl _OMPI_SETUP_PRRTE_INTERNAL([action-if-success], [action-if-not-success])
 dnl
 dnl Attempt to configure the built-in PRRTE.
@@ -220,7 +243,15 @@ AC_DEFUN([_OMPI_SETUP_PRRTE_INTERNAL], [
           [AC_MSG_ERROR([PRRTE configuration failed.  Cannot continue.])])
 
     AS_IF([test "$internal_prrte_happy" = "yes"],
-          [$1], [$2])
+          [AC_MSG_CHECKING([for internal PRRTE RST files])
+           AS_IF([test -n "$SPHINX_BUILD"],
+                 [OMPI_HAVE_PRRTE_RST=1
+                  OMPI_PRRTE_RST_CONTENT_DIR="$OMPI_TOP_SRCDIR/3rd-party/prrte/src/docs/prrte-rst-content"
+                  OMPI_SCHIZO_OMPI_RST_CONTENT_DIR="$OMPI_TOP_SRCDIR/3rd-party/prrte/src/mca/schizo/ompi"
+                  AC_MSG_RESULT([found])],
+		 [AC_MSG_RESULT([not found])])
+           $1],
+	  [$2])
 
     OPAL_VAR_SCOPE_POP
 ])
@@ -284,9 +315,27 @@ AC_DEFUN([_OMPI_SETUP_PRRTE_EXTERNAL], [
           [AC_DEFINE_UNQUOTED([OMPI_PRTERUN_PATH], ["${prterun_path}"], [Path to prterun])])
 
     AS_IF([test "$setup_prrte_external_happy" = "yes"],
-          [$1], [$2])
+          [ # Determine if this external PRRTE has installed the RST
+            # directories that we care about
+
+           AC_MSG_CHECKING([for external PRRTE RST files])
+           prrte_install_dir=${with_prrte}/share/prte/rst
+           AS_IF([test -n "$SPHINX_BUILD"],
+                 [AS_IF([test -d "$prrte_install_dir/prrte-rst-content" && \
+                         test -d "$prrte_install_dir/schizo-ompi-rst-content"],
+                        [OMPI_HAVE_PRRTE_RST=1
+                         OMPI_PRRTE_RST_CONTENT_DIR="$prrte_install_dir/prrte-rst-content"
+                         OMPI_SCHIZO_OMPI_RST_CONTENT_DIR="$prrte_install_dir/schizo-ompi-rst-content"
+                         AC_MSG_RESULT([found])
+                         ],
+                        [ # This version of PRRTE doesn't have installed RST
+                          # files.
+                          AC_MSG_RESULT([not found])
+                          OMPI_HAVE_PRRTE_RST=0
+                        ])
+                 ])
+           $1],
+	  [$2])
 
     OPAL_VAR_SCOPE_POP
 ])
-
-

configure.ac

@@ -28,6 +28,7 @@
 # Copyright (c) 2018      FUJITSU LIMITED.  All rights reserved.
 # Copyright (c) 2019      Triad National Security, LLC. All rights
 #                         reserved.
+# Copyright (c) 2023      Jeffrey M. Squyres.  All rights reserved.
 # $COPYRIGHT$
 #
 # Additional copyrights may follow
@@ -1072,7 +1073,7 @@ AS_IF([test -z "$LEX" || \
 
 dnl Note that we have to double escape the URL below
 dnl so that the # it contains doesn't confuse the Autotools
-OAC_SETUP_SPHINX([$srcdir/docs/_build/man/MPI_T.3],
+OAC_SETUP_SPHINX([$srcdir/docs/man/MPI_T.3],
                  [[https://docs.open-mpi.org/en/main/developers/prerequisites.html#sphinx-and-therefore-python]])
 
 #