wip -- update to match prrte (proposed) PR

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

config/ompi_setup_prrte.m4

@@ -19,13 +19,40 @@ 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
 dnl
 dnl $HEADER$
 dnl
 
+dnl $1 dir
+dnl $2 filename
+AC_DEFUN([_OMPI_SETUP_PRRTE_DUMMY_RST_FILE], [
+    dir=$1
+    file=$2
+
+    mkdir -p "$dir"
+    rm -rf "$dir/$file"
+    cat > "$dir/$file" <<EOF
+No content
+==========
+
+There is no meaningful content in this file because Open MPI was built
+with a PRRTE that was too old to include machine-readable
+documentation that could be incorporated into Open MPI's
+documentation.  If you build Open MPI with a newer version of PRRTE
+(and have the Sphinx tool available when you run Open MPI's
+``configure`` command), you should get more meaningful documentation
+here.
+
+Hence, there's no documentation for this section.
+
+Sorry!
+EOF
+])
+
 dnl Check for / configure PRRTE package.  Prefer finding an external
 dnl PRRTE, build our internal one if required.  If we can not find an
 dnl external PRRTE and the internal one fails to configure, abort.
@@ -35,10 +62,17 @@ 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])
+    OPAL_VAR_SCOPE_PUSH([prrte_setup_internal_happy prrte_setup_external_happy target_rst_dir])
 
     opal_show_subtitle "Configuring PRRTE"
 
+    # These are sym links to PRRTE's RST files that we'll slurp into
+    # mpirun.1.rst.  We'll remove these links now and replace them
+    # with new links to the PRRTE that we find, below.
+    target_rst_dir="$OMPI_TOP_SRCDIR/docs/man-openmpi/man1"
+    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],
@@ -220,7 +254,9 @@ AC_DEFUN([_OMPI_SETUP_PRRTE_INTERNAL], [
           [AC_MSG_ERROR([PRRTE configuration failed.  Cannot continue.])])
 
     AS_IF([test "$internal_prrte_happy" = "yes"],
-          [$1], [$2])
+          [${LN_S} $OMPI_TOP_SRCDIR/3rd-party/prrte/src/docs/prrte-rst-content $target_rst_dir
+           ${LN_S} $OMPI_TOP_SRCDIR/3rd-party/prrte/src/mca/schizo/ompi $target_rst_dir/schizo-ompi-rst-content
+           $1], [$2])
 
     OPAL_VAR_SCOPE_POP
 ])
@@ -284,9 +320,25 @@ 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])
+          [prrte_install_dir=${with_prrte}/share/prte/rst
+	   AS_IF([test -f "$prrte_install_dir"],
+                 [${LN_S} "$prrte_install_dir/prrte-rst-content" "$target_rst_dir"
+                  ${LN_S} "$prrte_install_dir/schizo-ompi-rst-content" "$target_rst_dir"],
+                 [ # This version of PRRTE doesn't have installed RST
+		   # files.  So we make dummy "you don't get help" RST
+		   # files.  Open to suggestion to do something
+		   # better...?
+		   _OMPI_SETUP_PRRTE_DUMMY_RST_FILE(
+		        [$target_rst_dir/prrte-rst-content],
+		        [cli-add-host.rst])
+		   _OMPI_SETUP_PRRTE_DUMMY_RST_FILE(
+		        [$target_rst_dir/schizo-ompi-rst-content],
+		        [schizo-ompi-cli.rst])
+		   _OMPI_SETUP_PRRTE_DUMMY_RST_FILE(
+		        [$target_rst_dir/prrte-rst-content],
+		        [deprecated-bind-to-core.rst])
+		   ])
+           $1], [$2])
 
     OPAL_VAR_SCOPE_POP
 ])
-
-

docs/Makefile.am

@@ -1,6 +1,7 @@
 #
 # Copyright (c) 2022 Cisco Systems, Inc.  All rights reserved.
 #
+# Copyright (c) 2023      Jeffrey M. Squyres.  All rights reserved.
 # $COPYRIGHT$
 #
 # Additional copyrights may follow
@@ -963,3 +964,7 @@ uninstall-hook:
 	rm -rf $(DESTDIR)$(docdir)
 
 endif OPAL_INSTALL_DOCS
+
+DIST_CLEANFILES = \
+        man/man1/prrte-rst-content \
+        man/man1/schizo-ompi-rst-content

docs/conf.py

@@ -13,7 +13,7 @@
 import os
 import sys
 sys.path.insert(0, os.path.abspath('./_ext'))
-extensions = [ 'prte' ]
+extensions = [ ]
 
 # -- Project information -----------------------------------------------------
 

docs/installing-open-mpi/packagers.rst

@@ -20,9 +20,26 @@ the following:
 
 .. code-block:: sh
 
+   # Install Sphinx so that Open MPI can re-build its docs with the
+   # installed PRRTE's docs
+
+   virtualalenv venv
+   . ./venv/bin/activate
+   pip install docs/requirements.txt
+
    ./configure --with-libevent=external --with-hwloc=external \
        --with-pmix=external --with-prrte=external ...
 
+.. important:: Note the installation of the Sphinx tool so that Open
+               MPI can re-build its documentation with the external
+               PRRTE's documentation.
+
+               Failure to do this will mean Open MPI's documentation
+               will be correct for the version of PRRTE that is
+               bundled in the Open MPI distribution, but may not be
+               entirely correct for the version of PRRTE that you are
+               building against.
+
 The ``external`` keywords will force Open MPI's ``configure`` to
 ignore all the bundled libraries and only look for external versions
 of these support libraries.  This also has the benefit of causing

docs/man-openmpi/man1/.gitignore

@@ -0,0 +1,3 @@
+# Sym links to PRRTE RST files
+prrte-rst-content
+schizo-ompi-rst-content