Merge pull request #11820 from jsquyres/pr/generate-mpirun-man-page

Include PRTE RST content in mpirun.1 man page

.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

.mailmap

@@ -32,6 +32,7 @@
 Jeff Squyres <[email protected]> <[email protected]>
 Jeff Squyres <[email protected]> --quiet <--quiet>
 Jeff Squyres <[email protected]>
+Jeff Squyres <[email protected]>
 
 George Bosilca <[email protected]> <[email protected]>
 

.readthedocs-pre-create-environment.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+set -euxo pipefail
+
+# The ReadTheDocs build process does not run autogen/configure/make.
+# Hence, we have to copy the PRRTE RST files (from the 3rd-party/prrte
+# tree) to our docs/ tree manually.
+
+# Ensure that we're in the RTD CI environment
+
+if [[ "${READTHEDOCS:-no}" == "no" ]]; then
+    echo "This script is only intended to be run in the ReadTheDocs CI environment"
+    exit 1
+fi
+
+SCHIZO_SRC_DIR=3rd-party/prrte/src/mca/schizo/ompi
+SCHIZO_TARGET_DIR=docs/schizo-ompi-rst-content
+
+PRRTE_RST_SRC_DIR=3rd-party/prrte/src/docs/prrte-rst-content
+PRRTE_RST_TARGET_DIR=docs/prrte-rst-content
+
+# Copy the OMPI schizo file from PRRTE
+
+cp -rp $SCHIZO_SRC_DIR $SCHIZO_TARGET_DIR
+
+# Only copy the PRRTE RST source files in prrte-rst-content that are
+# referenced by ".. include::" in the schizo-ompi-cli.rst file.  We do
+# this because Sphinx complains if there are .rst files that are not
+# referenced.  :-(
+
+mkdir -p $PRRTE_RST_TARGET_DIR
+files=`fgrep '.. include::' $SCHIZO_TARGET_DIR/schizo-ompi-cli.rstxt | awk '{ print $3 }'`
+for file in $files; do
+    filename=`basename $file`
+    cp -pf $PRRTE_RST_SRC_DIR/$filename $PRRTE_RST_TARGET_DIR
+done

.readthedocs.yaml

@@ -12,6 +12,11 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
+  jobs:
+    # RTD doesn't run configure or make.  So we have to manually copy
+    # in the PRRTE RST files to docs/.
+    pre_create_environment:
+      - ./.readthedocs-pre-create-environment.sh
 
 python:
   install:
@@ -21,3 +26,6 @@ python:
 sphinx:
   configuration: docs/conf.py
   fail_on_warning: true
+
+submodules:
+  include: all

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,25 @@ 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).
+    OAC_ASSERT_BEFORE([OAC_SETUP_SPHINX], [OMPI_SETUP_PRRTE])
+
+    # 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 +117,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 +239,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 +311,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]])
 
 #