Merge pull request open-mpi#12120 from jsquyres/pr/update-to-match-new-prte-docs

docs: update to match PRRTE v3.0.3 docs

Author: jsquyres

.readthedocs-pre-create-environment.sh

@@ -20,17 +20,9 @@ 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
+#
+# See lengthy comment in docs/Makefile.am about copying in RST files
+# from PRRTE for a longer explanation of what is happening here.
 
 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
+cp -rp $PRRTE_RST_SRC_DIR $PRRTE_RST_TARGET_DIR

3rd-party/prrte

@@ -1008,11 +1008,6 @@ $(ALL_MAN_BUILT): $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG)
 # changed.  We're going to overwrite any local changes in the build
 # tree, but you shouldn't be editing the build tree, anyway.  So --
 # good enough.
-#
-# Finally, one added wrinkle: only copy the RST source files in
-# prrte-rst-content that are referenced by ".. include::" in the
-# schizo-ompi-cli.rstxt file.  We do this because Sphinx complains if
-# there are .rst files that are not referenced.  :-(
 $(ALL_MAN_BUILT):
 	$(OMPI_V_SPHINX_COPYRST) if test "$(srcdir)" != "$(builddir)"; then \
 	    len=`echo "$(srcdir)/" | wc -c`; \
@@ -1027,10 +1022,9 @@ $(ALL_MAN_BUILT):
 	        cp -p "$$file" "$$dir"; \
 	    done; \
 	fi; \
-	for file in `fgrep '.. include::' $(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt | awk '{ print $$3 }'`; do \
-	    filename=`basename $$file`; \
-	    cp -pf $(OMPI_PRRTE_RST_CONTENT_DIR)/$$filename "$(builddir)/prrte-rst-content"; \
-	done
+	cp -rpf "$(OMPI_PRRTE_RST_CONTENT_DIR)" "$(builddir)"; \
+	copied_dir=`basename $(OMPI_PRRTE_RST_CONTENT_DIR)`; \
+	chmod -R u+w "$(builddir)/$$copied_dir"
 	$(OMPI_V_SPHINX_HTML) OMPI_TOP_SRCDIR=$(top_srcdir) $(SPHINX_BUILD) -M html "$(builddir)" "$(OUTDIR)" $(SPHINX_OPTS)
 	$(OMPI_V_SPHINX_MAN) OMPI_TOP_SRCDIR=$(top_srcdir) $(SPHINX_BUILD) -M man "$(builddir)" "$(OUTDIR)" $(SPHINX_OPTS)
 

docs/Makefile.am

@@ -176,7 +176,31 @@ def get_tarball_version(path, expr):
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv', 'py*/**']
+#
+# Note that we exclude the entire prrte-rst-content/ directory.
+# Here's why:
+#
+# * By default, Sphinx will warn about any .rst file that it finds in
+#   the doc tree that is not referenced via either the "include"
+#   directive or via a TOC.
+# * The prrte-rst-content/ directory contains files that we *do* use
+#   here in the OMPI docs, but it also contains files that we do
+#   *not* use here in the OMPI docs.
+# * Consequently, we explicitly ".. include:: <filename>" the specific
+#   files that we want from the prrte-rst-content/ directory.  And we
+#   specifically do *not* include at least some files in the
+#   prrte-rst-content directory.
+# * Listing files/patterns in exclude_patterns:
+#   * Will prevent Sphinx from searching for/finding new .rst files
+#     that match those patterns.
+#   * Will not prevent explicitly ".. include:"'ing a file with a name
+#     that matches a pattern in exclude_patterns.
+#
+# Hence, listing prrte-rst-content in exclude_patterns means that
+# Sphinx won't complain about the .rst files in that tree that we are
+# not referencing from here in the OMPI docs.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv', 'py*/**',
+                    'prrte-rst-content' ]
 
 
 # Clarify the language for verbatim blocks (::)