docs: update to match PRRTE v3.0.3 docs

With this update, OMPI supports the RST docs that were released as
part of PRRTE v3.0.2, but will also support the PRRTE RST docs for the
upcoming v3.0.3.

Signed-off-by: Jeff Squyres <[email protected]>
(cherry picked from commit 811a7f1)

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

docs/Makefile.am

@@ -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/conf.py

@@ -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 (::)