FIXUP -- to be squashed

Brian: I think I fixed the "make" issues I was seeing, and an
additional Sphinx issue that I was surprised by.  See the Makefile.am
comment in this fixup commit for an explanation.

This will eventually be squashed; I wanted to make it a separate
commit in case you had already started reviewing docs/Makefile.am.

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

docs/Makefile.am

@@ -928,31 +928,48 @@ include $(top_srcdir)/Makefile.ompi-rules
 # 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.
+
+# Make the 2 directories that we need: schizo-ompi-rst-content and
+# prrte-rst-content.
 $(builddir)/schizo-ompi-rst-content:
 	$(OMPI_V_MKDIR) if test ! -d "$@"; then mkdir "$@"; fi
-if OMPI_HAVE_PRRTE_RST
-	$(OMPI_V_SPHINX_COPYRST) cp -r $(OMPI_SCHIZO_OMPI_RST_CONTENT_DIR)/* "$@"
-else
-	$(OMPI_V_GEN) cp -pf $(srcdir)/no-prrte-content.rst.txt "$@/schizo-ompi-cli.rst"
-endif
-
-# See the comment above schizo-ompi-rst-content.  One added wrinkle:
-# only copy the 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.  :-(
-$(builddir)/prrte-rst-content: $(builddir)/schizo-ompi-rst-content
+$(builddir)/prrte-rst-content:
 	$(OMPI_V_MKDIR) if test ! -d "$@"; then mkdir "$@"; fi
+
+# Get the schizo-ompi-rst-cli.rst file that we need.  CAVEAT: we name
+# it ".in" so that Sphinx doesn't slurp it in via two different
+# locations in the RST docroot (i.e., via
+# /schizo-ompi-rst-content/schizo-ompi-cli.rstxt and via
+# /man-openmpi/man1/mpirun.1.rst).  Sphinx *shouldn't* do this -- it
+# should see the ".. include...." directive in mpirun.1.rst and *only*
+# include the file once.  But somehow it's also seeing it a 2nd time.
+# So -- fine.  We'll name it something other than .rst so that Sphinx
+# doesn't do that.
+#
+# Regardless, either copy this file from the PRRTE install tree or
+# make a bogus one (if we don't have one in the PRRTE install tree).
+#
+# Also, note: the rule to make the $(builddir)/schizo-ompi-rst-content
+# directory must be in the AM_CONDITIONAL here, otherwise Automake
+# complains.  Meaning: we have to have same dependency listed in both
+# the "if" and the "else" blocks.  Grumble.
 if OMPI_HAVE_PRRTE_RST
+$(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt: $(builddir)/schizo-ompi-rst-content
+$(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt: $(OMPI_SCHIZO_OMPI_RST_CONTENT_DIR)/*
 	$(OMPI_V_SPHINX_COPYRST) \
-	for file in `fgrep '.. include::' $(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rst | awk '{ print $$3 }'`; do \
-	    filename=`basename $$file`; \
-	    cp -pf $(OMPI_PRRTE_RST_CONTENT_DIR)/$$filename "$@"; \
-	done
+	dir=`dirname $@`; \
+	cp -rpf $(OMPI_SCHIZO_OMPI_RST_CONTENT_DIR)/* "$$dir"
+else
+$(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt: $(builddir)/schizo-ompi-rst-content
+$(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt: $(srcdir)/no-prrte-content.rst.txt
+	if test ! -d "$$dir"; then mkdir "$$dir"; fi
+	$(OMPI_V_SPHINX_COPYRST) \
+	dir=`dirname $@`; \
+	cp -pf $(srcdir)/no-prrte-content.rst.txt "$$dir"
 endif
 
 $(ALL_MAN_BUILT): $(builddir)/prrte-rst-content
-$(ALL_MAN_BUILT): $(builddir)/schizo-ompi-rst-content
+$(ALL_MAN_BUILT): $(builddir)/schizo-ompi-rst-content/schizo-ompi-cli.rstxt
 $(ALL_MAN_BUILT): $(RST_SOURCE_FILES) $(IMAGE_SOURCE_FILES)
 $(ALL_MAN_BUILT): $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG)
 
@@ -992,6 +1009,11 @@ $(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`; \
@@ -1005,7 +1027,11 @@ $(ALL_MAN_BUILT):
 	        fi; \
 	        cp -p "$$file" "$$dir"; \
 	    done; \
-	fi
+	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
 	$(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)
 

docs/man-openmpi/man1/mpirun.1.rst

@@ -103,7 +103,7 @@ The core of Open MPI's ``mpirun`` processing is performed via the
 effectively a wrapper around ``prterun``, but ``mpirun``'s CLI options
 are slightly different than PRRTE's CLI commands.
 
-.. include:: /schizo-ompi-rst-content/schizo-ompi-cli.rst
+.. include:: /schizo-ompi-rst-content/schizo-ompi-cli.rstxt
 
 OPTIONS (OLD / HARD-CODED CONTENT -- TO BE AUDITED
 --------------------------------------------------