docs:update tcp tuning page

reference prrte docs for prrte tcp related mca parameters.

use intersphinx to avoid needing to use external URL
references.

Signed-off-by: Howard Pritchard <howardp@lanl.gov>

Author: hppritcha

docs/Makefile.am

@@ -1095,8 +1095,8 @@ $(ALL_MAN_BUILT):
 	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)
+	$(OMPI_V_SPHINX_HTML) OMPI_TOP_SRCDIR=$(top_srcdir) OMPI_PREFIX=$(prefix) $(SPHINX_BUILD) -M html "$(builddir)" "$(OUTDIR)" $(SPHINX_OPTS)
+	$(OMPI_V_SPHINX_MAN) OMPI_TOP_SRCDIR=$(top_srcdir) OMPI_PREFIX=$(prefix) $(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

docs/conf.py

@@ -31,6 +31,12 @@
 ompi_top_srcdir = '..'
 if 'OMPI_TOP_SRCDIR' in os.environ:
     ompi_top_srcdir = os.environ['OMPI_TOP_SRCDIR']
+ompi_prefix = ''
+if 'OMPI_PREFIX' in os.environ:
+    ompi_prefix = os.environ['OMPI_PREFIX']
+else:
+    print(f"ERROR: Unable to find install path")
+    exit(1)
 
 # Read an Open MPI-style VERSION file
 def read_version_file(path):
@@ -178,8 +184,24 @@ def get_tarball_version(path, expr):
     'recommonmark',
     "sphinx_rtd_theme",
     "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
 ]
 
+# conf.py file
+
+intersphinx_mapping = {
+    "prrte": (f"{ompi_prefix}/share/doc/prrte/html", None),
+    "pmix": (f"{ompi_prefix}/share/doc/pmix/html", None),
+}
+
+# We recommend adding the following config value.
+# Sphinx defaults to automatically resolve *unresolved* labels using all your Intersphinx mappings.
+# This behavior has unintended side-effects, namely that documentations local references can
+# suddenly resolve to an external location.
+# See also:
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
+intersphinx_disabled_reftypes = ["*"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/tuning-apps/networking/tcp.rst

@@ -247,20 +247,15 @@ not use specific IP networks |mdash| or not use any IP networks at all
 .. warning:: If you use the ``btl_tcp_if_include`` and
              ``btl_tcp_if_exclude`` MCA parameters to shape the
              behavior of the TCP BTL for MPI communications, you may
-             also need/want to investigate the corresponding MCA
-             parameters ``oob_tcp_if_include`` and
-             ``oob_tcp_if_exclude``, which are used to shape non-MPI
-             TCP-based communication (e.g., communications setup and
-             coordination during ``MPI_INIT`` and ``MPI_FINALIZE``).
-
-.. error:: TODO do corresponding OOB TCP params still exist in PMIx?
-
-Note that Open MPI will still use TCP for control messages, such as
-data between ``mpirun`` and the MPI processes, rendezvous information
-during ``MPI_INIT``, etc.  To disable TCP altogether, you also need to
-disable the ``tcp`` component from the OOB framework.
-
-.. error:: TODO Is this possible in PMIx?  I doubt it...?
+             also need/want to investigate the corresponding PRRTE
+             parameters that control use of network interfaces by the runtime
+             (e.g., communications setup and coordination during
+             ``MPI_INIT`` and ``MPI_FINALIZE``) using the :ref:`prte_info <prrte:man1-ompi-prte_info>`
+             and :ref:`pmix_info <pmix:man1-pmix_info>` commands.
+
+Note that the Open MPI runtime uses TCP for control messages, such as
+for data exchange between ``mpirun`` and the MPI processes, rendezvous information
+during ``MPI_INIT``, etc. even if the ``tcp`` BTL component is disabled.
 
 /////////////////////////////////////////////////////////////////////////