wip

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

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,10 @@ OMPI_V_GEN = $(ompi__v_GEN_$V)
 ompi__v_GEN_ = $(ompi__v_GEN_$AM_DEFAULT_VERBOSITY)
 ompi__v_GEN_0 = @echo "  GENERATE" $@;
 
+OMPI_V_SPHINX_COPYALL = $(ompi__v_SPHINX_COPYALL_$V)
+ompi__v_SPHINX_COPYALL_ = $(ompi__v_SPHINX_COPYALL_$AM_DEFAULT_VERBOSITY)
+ompi__v_SPHINX_COPYALL_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

@@ -52,9 +52,10 @@ OPAL_VAR_SCOPE_PUSH([prrte_setup_internal_happy prrte_setup_external_happy targe
     # 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 now and
-    # replace them with new links to the PRRTE that we find, below.
-    target_rst_dir="$OMPI_TOP_SRCDIR/docs"
+    # 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"
 
@@ -112,11 +113,6 @@ OPAL_VAR_SCOPE_PUSH([prrte_setup_internal_happy prrte_setup_external_happy targe
     AM_CONDITIONAL([OMPI_WANT_PRRTE],
            [test "$prrte_setup_internal_happy" = "1" -o "$prrte_setup_external_happy" = "1"])
 
-    # If we are building Sphinx docs but are not building PRRTE, make
-    # dummy PRRTE docs files
-    AS_IF([test -x "$SPHINX_BUILD" && test $OMPI_HAVE_PRRTE -eq 0],
-          [_OMPI_SETUP_PRRTE_DUMMY_RST_FILES])
-
     AC_DEFINE_UNQUOTED([OMPI_HAVE_PRRTE],
                        [$OMPI_HAVE_PRRTE],
                        [Whether or not PRRTE is available])
@@ -125,75 +121,11 @@ OPAL_VAR_SCOPE_PUSH([prrte_setup_internal_happy prrte_setup_external_happy targe
                        [$OMPI_USING_INTERNAL_PRRTE],
                        [Whether or not we are using the internal PRRTE])
 
-    OPAL_SUMMARY_ADD([Miscellaneous], [PRRTE], [], [$opal_prrte_mode])
-
-    OPAL_VAR_SCOPE_POP
-])
-
-dnl Helper to make a dummy RST file in a specific target directory.
-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 either:
-
-* Built without PRRTE support.
-
-* Built with a PRRTE that was too old to include machine-readable
-  documentation that could be incorporated into Open MPI's
-  documentation.
+    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])
 
-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
-])
-
-AC_DEFUN([_OMPI_SETUP_PRRTE_DUMMY_RST_FILES], [
-    _OMPI_SETUP_PRRTE_DUMMY_RST_FILE(
-        [$target_rst_dir/prrte-rst-content],
-        [prterun-all-cli.rst])
-    _OMPI_SETUP_PRRTE_DUMMY_RST_FILE(
-        [$target_rst_dir/prrte-rst-content],
-        [prterun-all-deprecated.rst])
-    _OMPI_SETUP_PRRTE_DUMMY_RST_FILE(
-        [$target_rst_dir/schizo-ompi-rst-content],
-        [schizo-ompi-cli.rst])
-    AC_MSG_NOTICE([created dummy PRRTE RST files])
-])
-
-
-dnl Helper to ensure that a source directory exists before making a
-dnl sym link to it.
-dnl
-dnl $1 source directory
-dnl $2 target directory
-AC_DEFUN([_OMPI_SETUP_PRRTE_CHECK_AND_LINK], [
-    OPAL_VAR_SCOPE_PUSH([src dest])
-
-    src="$1"
-    dest="$2"
-
-    AS_IF([test ! -d "$src"],
-          [AC_MSG_RESULT([not found])
-           AC_MSG_WARN([Directory $src does not exist])
-           AC_MSG_WARN([This should never happen])
-           AC_MSG_ERROR([Cannot continue])])
-    ${LN_S} "$src" "$dest"
+    OPAL_SUMMARY_ADD([Miscellaneous], [PRRTE], [], [$opal_prrte_mode])
 
     OPAL_VAR_SCOPE_POP
 ])
@@ -312,12 +244,9 @@ AC_DEFUN([_OMPI_SETUP_PRRTE_INTERNAL], [
 
     AS_IF([test -n "$SPHINX_BUILD" && test "$internal_prrte_happy" = "yes"],
           [AC_MSG_CHECKING([for internal PRRTE RST files])
-           _OMPI_SETUP_PRRTE_CHECK_AND_LINK(
-              [$OMPI_TOP_SRCDIR/3rd-party/prrte/src/docs/prrte-rst-content],
-              [$target_rst_dir/prrte-rst-content])
-           _OMPI_SETUP_PRRTE_CHECK_AND_LINK(
-              [$OMPI_TOP_SRCDIR/3rd-party/prrte/src/mca/schizo/ompi],
-              [$target_rst_dir/schizo-ompi-rst-content])
+           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])
            $1], [$2])
 
@@ -391,17 +320,16 @@ AC_DEFUN([_OMPI_SETUP_PRRTE_EXTERNAL], [
            prrte_install_dir=${with_prrte}/share/prte/rst
            AS_IF([test -d "$prrte_install_dir/prrte-rst-content" && \
                   test -d "$prrte_install_dir/schizo-ompi-rst-content"],
-                 [${LN_S} "$prrte_install_dir/prrte-rst-content" "$target_rst_dir"
-                  ${LN_S} "$prrte_install_dir/schizo-ompi-rst-content" "$target_rst_dir"
+                 [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.  So we make dummy "you don't get help" RST
-                   # files.  Open to suggestion to do something
-                   # better...?
-                   AC_MSG_RESULT([not found (made empty dummy files)])
-                   _OMPI_SETUP_PRRTE_DUMMY_RST_FILES
-                   ])
+                   # files.
+                   AC_MSG_RESULT([not found])
+                   OMPI_HAVE_PRRTE_RST=0
+                  ])
            $1], [$2])
 
     OPAL_VAR_SCOPE_POP

docs/Makefile.am

@@ -27,7 +27,7 @@
 .NOTPARALLEL:
 
 OUTDIR             = _build
-SPHINX_CONFIG      = conf.py
+SPHINX_CONFIG      = $(srcdir)/conf.py
 SPHINX_OPTS       ?= -W --keep-going -j auto
 
 # Note: it is significantly more convenient to list all the source
@@ -59,6 +59,7 @@ RST_SOURCE_FILES   = \
 
 EXTRA_DIST         = \
         requirements.txt \
+        no-prrte-content.rst.txt \
         $(SPHINX_CONFIG) \
         $(TEXT_SOURCE_FILES) \
         $(IMAGE_SOURCE_FILES) \
@@ -863,32 +864,158 @@ EXTRA_DIST += \
         $(OUTDIR)/html \
         $(OUTDIR)/man
 
+# Copy over the PRRTE RST files to this build tree.
+#
+# NOTE: We specifically list $(builddir) in the target name, just to
+# ensure that "make" doesn't accidentally find this directory in the
+# VPATH srcdir, and therefore not execute this rule (because Sphinx
+# does not understand VPATH, and will ignore this directory in the
+# VPATH srcdir).  We can have this directory in the srcdir by doing a
+# VPATH build of an official distribution tarball.
+$(builddir)/prrte-rst-content:
+	$(OMPI_V_MKDIR) mkdir "$@"
+if OMPI_HAVE_PRRTE_RST
+	$(OMPI_V_SPHINX_COPYALL) cp -r $(OMPI_PRRTE_RST_CONTENT_DIR)/* "$@"
+else
+	$(OMPI_V_GEN) cp -f $(srcdir)/no-prrte-content.rst.txt "$@/prterun-all-cli.rst"
+	$(OMPI_V_GEN) cp -f $(srcdir)/no-prrte-content.rst.txt "$@/prterun-all-deprecated.rst"
+endif
+
+# See the comment above prrte-rst-content.
+$(builddir)/schizo-ompi-rst-content:
+	$(OMPI_V_MKDIR) mkdir "$@"
+if OMPI_HAVE_PRRTE_RST
+	$(OMPI_V_SPHINX_COPYALL) cp -r $(OMPI_SCHIZO_OMPI_RST_CONTENT_DIR)/* "$@"
+else
+	$(OMPI_V_GEN) cp -f $(srcdir)/no-prrte-content.rst.txt "$@/schizo-ompi-cli.rst"
+endif
+
 ALL_MAN_BUILT = \
         $(OMPI_MAN1_BUILT) $(OMPI_MAN3_BUILT) $(OMPI_MAN7_BUILT) \
         $(OSHMEM_MAN1_BUILT) $(OSHMEM_MAN_3_BUILT)
+$(ALL_MAN_BUILT): $(builddir)/prrte-rst-content
+$(ALL_MAN_BUILT): $(builddir)/schizo-ompi-rst-content
 $(ALL_MAN_BUILT): $(RST_SOURCE_FILES) $(IMAGE_SOURCE_FILES)
 $(ALL_MAN_BUILT): $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG)
 
+# Render the RST source into both 1) full HTML docs and 2) nroff man
+# pages.
+#
 # List both commands (HTML and man) in a single rule because they
 # really need to be run in serial.  Specifically, if they were two
 # different rules and someone ran "make -j", then both of them could
 # be writing to $(OUTDIR)/doctrees simultaneously, which would be Bad.
 # Use one of the man pages as a sentinel file to indicate whether all
 # the HTML docs and man pages have been built.
+#
+# It's therefore a little bit of a lie to have the target named
+# $(ALL_MAN_BUILT) *also* generate all the HTML content, but... so be
+# it.
+#
+# Also note that Open MPI's RST includes some conditional RST, meaning
+# that:
+#
+# 1. If we're building with PRRTE support:
+#
+#    1a. If we're building the internal/bundled PRRTE, then we'll copy
+#        the internal/bundled PRRTE's RST files to the build tree.
+#    1b. If we're building against an external PRRTE installation that
+#        has RST files in its install tree, then we'll copy that
+#        external PRRTE's RST files to the build tree.
+#    1c. If we're building against an external PRRTE installation that
+#        does NOT have RST files in its install tree, then we'll
+#        create some dummy RST files instead.
+#
+# 2. If we're building without PRRTE support, we'll create some dummy
+# RST files instead.
+#
+# The above conditionals mean that we have to make some changes to the
+# input Sphinx RST tree before building it.  But -- by Automake
+# convention -- we can't modify the source tree.  Hence, we have to
+# copy over all the source RST files -- including its internal
+# directory structure -- to the build tree, and then make our desired
+# changes here in the build tree.  This is a bit ugly, but we could
+# not think of anything better to do.
+#
+# NOTE: This is a little gross in that for a VPATH build, we *always*
+# copy from the source tree to the dest tree, such that "make all"
+# will always rebuild, even if there were no changes in the source
+# tree.  However, this is mitigated because we only do this copy if a)
+# the targets do not exist (e.g., the first VPATH build of a new
+# source tree), or b) if the sources are newer than the targets.  This
+# is a little unfortunate/gross for b), because if someone modifies
+# the .rst files here in the build tree, we'll overwrite their changes
+# with new copies from the source tree.
 $(ALL_MAN_BUILT):
-	$(OMPI_V_SPHINX_HTML) $(SPHINX_BUILD) -M html "$(srcdir)" "$(OUTDIR)" $(SPHINX_OPTS)
-	$(OMPI_V_SPHINX_MAN) $(SPHINX_BUILD) -M man "$(srcdir)" "$(OUTDIR)" $(SPHINX_OPTS)
+if OMPI_HAVE_PRRTE_RST
+	$(OMPI_V_SPHINX_COPYALL) if test "$(srcdir)" != "$(builddir)"; then \
+	    len=`echo "$(srcdir)/" | wc -c`; \
+	    for file in $(RST_SOURCE_FILES) $(IMAGE_SOURCE_FILES) $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG); do \
+	        dir=`dirname $$file | cut -c$$len-`; \
+	        if test -z "$$dir"; then \
+	            dir=.; \
+	        fi; \
+	        if test ! -d "$$dir"; then \
+	            mkdir -p "$$dir"; \
+	        fi; \
+	        cp -f "$$file" "$$dir"; \
+	    done; \
+	fi
+endif
+	$(OMPI_V_SPHINX_HTML) OMPI_VERSION_FILE=$(top_srcdir)/VERSION $(SPHINX_BUILD) -M html "$(builddir)" "$(OUTDIR)" $(SPHINX_OPTS)
+	$(OMPI_V_SPHINX_MAN) OMPI_VERSION_FILE=$(top_srcdir)/VERSION $(SPHINX_BUILD) -M man "$(builddir)" "$(OUTDIR)" $(SPHINX_OPTS)
 
 # A useful rule to invoke manually to ensure that all of the external
 # HTML links we have are valid.  Running this rule requires
 # connectivity to the general internet.
 linkcheck:
-	$(SPHINX_BUILD) -M linkcheck "$(srcdir)" "$(OUTDIR)" $(SPHINX_OPTS)
+	$(SPHINX_BUILD) -M linkcheck "$(builddir)" "$(OUTDIR)" $(SPHINX_OPTS)
 
 .PHONY: linkcheck
 
-maintainer-clean-local:
-	$(SPHINX_BUILD) -M clean "$(srcdir)" "$(OUTDIR)" $(SPHINX_OPTS)
+# Since we are building the docs, we built $(OUTDIR).  Hence, we need
+# to delete it during "make clean".  Note that we can't add
+# directories to CLEANFILES, because Automake only (effectively) does
+# "rm -f $(CLEANFILES)" (not "rm -rf ...").  So we have to delete
+# directories ourselves.
+#
+# Also, if this is a VPATH build, then we made a copy of a bunch of
+# RST source files to the build tree.  So delete all of those, too.
+#
+########################################################################
+# JMS: THIS IS WEIRD.  "make clean" is different, depending on whether
+# we're building the docs or not (i.e., whether configure found Sphinx
+# or not).  For example, you could:
+#
+# - un-tar an official distribution tarball
+# - run configure, find Sphinx
+# - make clean, and remove the pre-built _build/html (and man) that
+#   came in the tarball
+#
+# Should the tarball contain pre-built HTML/man trees in a different
+# location?  I.e., distinguish between what we ship in the tarball and
+# what you build?  Presumably, in that case, we'd install:
+#
+# - if you build the docs, install that
+# - otherwise, if the pre-build docs exist, install them
+#
+# And "make clean" could then just always rm -rf docs/_built.
+########################################################################
+clean-local:
+	rm -rf $(OUTDIR)
+	rm -rf prrte-rst-content schizo-ompi-rst-content
+	if test "$(srcdir)" != "$(builddir)"; then \
+	    len=`echo "$(srcdir)/" | wc -c`; \
+	    for file in $(RST_SOURCE_FILES) $(IMAGE_SOURCE_FILES) $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG); do \
+	        dir=`dirname $$file | cut -c$$len-`; \
+	        if test -z "$$dir"; then \
+	            rm -rf `basename $$file`; \
+	        fi; \
+	        if test -n "$$dir" && test -d "$$dir"; then \
+	            rm -rf "$$dir"; \
+	        fi; \
+	    done; \
+	fi
 
 # List all the built man pages here in the Automake BUILT_SOURCES
 # macro.  This hooks into the normal Automake build mechanisms, and
@@ -946,25 +1073,32 @@ endif
 # Automake-provided install macros to set desirable permissions on the
 # target directories and files.
 #
-# Since this might be a VPATH build, first check to see if _build/html
-# exists in the source tree.  If not, do the find+install from the
-# build tree.
+# Check to see if we actually built the docs.  If we did, copy from
+# the _build/html tree in the builddir.  In all other cases, see if
+# there's a _build/html in the source tree (e.g., if this is a build
+# from a tarball that included a _build/html); if that exists, copy
+# from that.
+#
+# NOTE: We can't use the AM_CONDITIONAL OPAL_BUILD_DOCS in the middle
+# of a block that uses the shell continuation character at the end of
+# each line.  Instead, we check if $(SPHINX_BUILD) is non-empty, which
+# is the test used to construct OPAL_BUILD_DOCS.
 install-data-hook:
 	$(MKDIR_P) $(DESTDIR)$(docdir)
-	if test -d $(srcdir)/_build/html; then \
-	    topdir=$(srcdir)/_build; \
-	else \
-	    topdir=_build; \
+	topdir= ; \
+	if test -n "$(SPHINX_BUILD)" && test -d $(builddir)/_build/html; then \
+	    topdir="$(builddir)/_build"; \
+	elif test -d $(srcdir)/_build/html; then \
+	    topdir="$(srcdir)/_build"; \
 	fi; \
-	cd $$topdir; \
-	find html -type d -exec $(mkinstalldirs) $(DESTDIR)$(docdir)/{} \; ; \
-	find html -type f -exec $(INSTALL_DATA) {} $(DESTDIR)$(docdir)/{} \;
+	if test -n "$$topdir"; then \
+	    echo JMS topdir is $$topdir; \
+	    cd $$topdir; \
+	    find html -type d -exec $(mkinstalldirs) $(DESTDIR)$(docdir)/{} \; ; \
+	    find html -type f -exec $(INSTALL_DATA) {} $(DESTDIR)$(docdir)/{} \; ; \
+	fi
 
 uninstall-hook:
 	rm -rf $(DESTDIR)$(docdir)
 
 endif OPAL_INSTALL_DOCS
-
-DIST_CLEANFILES = \
-        man/man1/prrte-rst-content \
-        man/man1/schizo-ompi-rst-content