v6.0.x: docs: update TCP docs + support deep linking into PMIx and PRTE docs

.gitignore

@@ -517,6 +517,7 @@ docs/_static
 docs/_static/css/custom.css
 docs/_templates
 docs/man-openmpi/man3/bindings
+docs/*.inv
 
 # Common Python virtual environment and cache directory names
 venv

config/ompi_setup_prrte.m4

@@ -19,7 +19,7 @@ dnl Copyright (c) 2019-2020 Intel, Inc.  All rights reserved.
 dnl Copyright (c) 2020-2022 Amazon.com, Inc. or its affiliates.  All Rights reserved.
 dnl Copyright (c) 2021      Nanook Consulting.  All rights reserved.
 dnl Copyright (c) 2021-2022 IBM Corporation.  All rights reserved.
-dnl Copyright (c) 2023-2024 Jeffrey M. Squyres.  All rights reserved.
+dnl Copyright (c) 2023-2025 Jeffrey M. Squyres.  All rights reserved.
 dnl Copyright (c) 2025      Advanced Micro Devices, Inc. All rights reserved.
 dnl $COPYRIGHT$
 dnl
@@ -39,7 +39,8 @@ dnl results of the build.
 AC_DEFUN([OMPI_SETUP_PRRTE],[
     AC_REQUIRE([AC_PROG_LN_S])
 
-OPAL_VAR_SCOPE_PUSH([prrte_setup_internal_happy prrte_setup_external_happy target_rst_dir])
+    OPAL_VAR_SCOPE_PUSH([prrte_setup_internal_happy prrte_setup_external_happy target_rst_dir ompi_external_prrte_docs_url])
+    ompi_external_prrte_docs_url="https://docs.prrte.org/en/latest/"
 
     opal_show_subtitle "Configuring PRRTE"
 
@@ -120,6 +121,8 @@ OPAL_VAR_SCOPE_PUSH([prrte_setup_internal_happy prrte_setup_external_happy targe
 
     AC_SUBST(OMPI_PRRTE_RST_CONTENT_DIR)
     AC_SUBST(OMPI_SCHIZO_OMPI_RST_CONTENT_DIR)
+    AC_SUBST(OMPI_PRRTE_DOCS_URL_BASE)
+    AC_SUBST(OMPI_USING_INTERNAL_PRRTE)
     AM_CONDITIONAL(OMPI_HAVE_PRRTE_RST, [test $OMPI_HAVE_PRRTE_RST -eq 1])
 
     AS_IF([test "$OMPI_USING_INTERNAL_PRRTE" = "1"],
@@ -250,8 +253,30 @@ AC_DEFUN([_OMPI_SETUP_PRRTE_INTERNAL], [
                  [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"
+
+                  # If we're building the OMPI Sphinx docs, and also
+                  # building the internal PRRTE, then we're *also*
+                  # building the internal PRRTE docs.
+                  #
+                  # In this case, the OMPI docs/conf.py will do a
+                  # bunch of processing that is a lot easier to do in
+                  # Python than Bourne shell (e.g., use the convenient
+                  # os.path.relpath() to compute the relative path
+                  # that we need, as well as dynamically create a
+                  # Sphinx link inventory file).  Hence, we skip doing
+                  # all that work here and just set a sentinel value
+                  OMPI_PRRTE_DOCS_URL_BASE="../../prrte/html"
                   AC_MSG_RESULT([found])],
-		 [AC_MSG_RESULT([not found])])
+                 [ # If we are not building the Sphinx docs, default
+                   # to using the external PRRTE docs URL.  This is
+                   # actually moot because we won't be building the
+                   # docs, but we might as well be complete in the
+                   # logic / cases.
+                  OMPI_PRRTE_DOCS_URL_BASE=$ompi_external_prrte_docs_url
+                  AC_MSG_RESULT([not found])])
+
+           AC_MSG_CHECKING([for internal PRRTE docs link URL base])
+           AC_MSG_RESULT([$OMPI_PRRTE_DOCS_URL_BASE])
            $1],
 	  [$2])
 
@@ -273,7 +298,7 @@ dnl _OMPI_SETUP_PRRTE_EXTERNAL([action if success], [action if not success])
 dnl
 dnl Try to find an external prrte with sufficient version.
 AC_DEFUN([_OMPI_SETUP_PRRTE_EXTERNAL], [
-    OPAL_VAR_SCOPE_PUSH([ompi_prte_min_version ompi_prte_min_num_version setup_prrte_external_happy opal_prrte_CPPFLAGS_save])
+    OPAL_VAR_SCOPE_PUSH([ompi_prte_min_version ompi_prte_min_num_version setup_prrte_external_happy opal_prrte_CPPFLAGS_save ompi_prrte_docdir])
 
     opal_prrte_CPPFLAGS_save=$CPPFLAGS
 
@@ -321,6 +346,10 @@ AC_DEFUN([_OMPI_SETUP_PRRTE_EXTERNAL], [
           [ # Determine if this external PRRTE has installed the RST
             # directories that we care about
 
+           # In the external case, initially assume we'll use the
+           # web-based docs
+           OMPI_PRRTE_DOCS_URL_BASE=$ompi_external_prrte_docs_url
+
            AC_MSG_CHECKING([for external PRRTE RST files])
            prrte_install_dir=${with_prrte}/share/prte/rst
            AS_IF([test -n "$SPHINX_BUILD"],
@@ -329,13 +358,27 @@ AC_DEFUN([_OMPI_SETUP_PRRTE_EXTERNAL], [
                         [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"
+                         # If the external PRTE docs dir exists where
+                         # a simple heuristic thinks it should be
+                         # (i.e., the default docdir location), use
+                         # it.  This will be an absolute path, which
+                         # is fine (because we're building against an
+                         # external PRRTE).  If we don't find it,
+                         # we'll fall back to the above-set HTTPS
+                         # internet PRRTE docs URL.
+                         ompi_prrte_docdir="$with_prrte/share/doc/prrte/html"
+                         AS_IF([test -d "$ompi_prrte_docdir"],
+                                [OMPI_PRRTE_DOCS_URL_BASE="$ompi_prrte_docdir"])
                          AC_MSG_RESULT([found])
                          ],
                         [ # This version of PRRTE doesn't have installed RST
                           # files.
                           AC_MSG_RESULT([not found])
                         ])
                  ])
+
+           AC_MSG_CHECKING([for external PRRTE docs link URL base])
+           AC_MSG_RESULT([$OMPI_PRRTE_DOCS_URL_BASE])
            $1],
 	  [$2])
 

config/opal_config_pmix.m4

@@ -21,6 +21,7 @@ dnl Copyright (c) 2020      Triad National Security, LLC. All rights
 dnl                         reserved.
 dnl Copyright (c) 2020-2022 Amazon.com, Inc. or its affiliates.  All Rights reserved.
 dnl Copyright (c) 2021      Nanook Consulting.  All rights reserved.
+dnl Copyright (c) 2025      Jeffrey M. Squyres.  All rights reserved.
 dnl $COPYRIGHT$
 dnl
 dnl Additional copyrights may follow
@@ -57,7 +58,8 @@ dnl         other execution tests later in configure (there are sadly
 dnl         some) would fail if the path in LDFLAGS was not added to
 dnl         LD_LIBRARY_PATH.
 AC_DEFUN([OPAL_CONFIG_PMIX], [
-    OPAL_VAR_SCOPE_PUSH([external_pmix_happy internal_pmix_happy internal_pmix_args internal_pmix_wrapper_libs internal_pmix_CPPFLAGS opal_pmix_STATIC_LDFLAGS opal_pmix_LIBS opal_pmix_STATIC_LIBS])
+    OPAL_VAR_SCOPE_PUSH([external_pmix_happy internal_pmix_happy internal_pmix_args internal_pmix_wrapper_libs internal_pmix_CPPFLAGS opal_pmix_STATIC_LDFLAGS opal_pmix_LIBS opal_pmix_STATIC_LIBS opal_external_pmix_docs_url])
+    opal_external_pmix_docs_url="https://docs.openpmix.org/en/latest/"
 
     opal_show_subtitle "Configuring PMIx"
 
@@ -154,6 +156,8 @@ AC_DEFUN([OPAL_CONFIG_PMIX], [
     AC_DEFINE_UNQUOTED([OPAL_USING_INTERNAL_PMIX],
                        [$OPAL_USING_INTERNAL_PMIX],
                        [Whether or not we are using the internal PMIx])
+    AC_SUBST(OPAL_PMIX_DOCS_URL_BASE)
+    AC_SUBST(OPAL_USING_INTERNAL_PMIX)
 
     OPAL_SUMMARY_ADD([Miscellaneous], [pmix], [], [$opal_pmix_mode])
 
@@ -216,8 +220,22 @@ AC_DEFUN([_OPAL_CONFIG_PMIX_EXTERNAL], [
                   dnl it will screw up other tests (like the pthread tests)
                   opal_pmix_BUILD_LIBS="${opal_pmix_LIBS}"
 
+                  # If the external PMIx docs dir exists where
+                  # a simple heuristic thinks it should be
+                  # (i.e., the default docdir location), use
+                  # it.  This will be an absolute path, which
+                  # is fine (because we're building against an
+                  # external PMIx).  If we don't find it,
+                  # we'll fall back to the HTTPS internet PMIx
+                  # docs URL.
+                  opal_pmix_docdir="$with_pmix/share/doc/pmix/html"
+                  AS_IF([test -d "$opal_pmix_docdir"],
+                        [OPAL_PMIX_DOCS_URL_BASE="$opal_pmix_docdir"],
+                        [OPAL_PMIX_DOCS_URL_BASE=$opal_external_pmix_docs_url])
+
                   $1],
-                 [$2])])
+                 [$2])
+     ])
 
     OPAL_VAR_SCOPE_POP
 ])
@@ -238,7 +256,7 @@ AC_DEFUN([_OPAL_CONFIG_PMIX_INTERNAL_POST], [
 
     pmix_internal_happy=1
 
-    dnl Don't pull LDFLAGS, because we don't have a good way to avoid
+    dnl Do not pull LDFLAGS, because we don't have a good way to avoid
     dnl a -L to our install directory, which can cause some weirdness
     dnl if there's an old OMPI install there.  And it makes filtering
     dnl redundant flags easier.
@@ -279,6 +297,31 @@ AC_DEFUN([_OPAL_CONFIG_PMIX_INTERNAL_POST], [
 
     opal_pmix_BUILD_LIBS="$OMPI_TOP_BUILDDIR/3rd-party/openpmix/src/libpmix.la"
 
+    AS_IF([test -n "$SPHINX_BUILD"],
+          [ # If we're building the OMPI Sphinx docs, and also
+            # building the internal PMIx, then we're *also*
+            # building the internal PMIx docs.
+            #
+            # In this case, the OMPI docs/conf.py will do a
+            # bunch of processing that is a lot easier to do in
+            # Python than Bourne shell (e.g., use the convenient
+            # os.path.relpath() to compute the relative path
+            # that we need, as well as dynamically create a
+            # Sphinx link inventory file).  Hence, we skip doing
+            # all that work here and just set a sentinel value
+            OPAL_PMIX_DOCS_URL_BASE="../../pmix/html"
+            AC_MSG_RESULT([found])],
+          [ # If we are not building the Sphinx docs, default
+            # to using the external PMIx docs URL.  This is
+            # actually moot because we won't be building the
+            # docs, but we might as well be complete in the
+            # logic / cases.
+            OPAL_PMIX_DOCS_URL_BASE=$opal_external_pmix_docs_url
+            AC_MSG_RESULT([not found])])
+
+    AC_MSG_CHECKING([for internal PMIx docs link URL base])
+    AC_MSG_RESULT([$OPAL_PMIX_DOCS_URL_BASE])
+
     OPAL_3RDPARTY_SUBDIRS="$OPAL_3RDPARTY_SUBDIRS openpmix"
 ])
 

contrib/update-my-copyright.pl

@@ -128,31 +128,13 @@ sub quiet_print {
 
 # Find the top-level source tree dir in a git repo
 my $start = cwd();
-my $top = $start;
-while (! -d "$top/.git") {
-    chdir("..");
-    $top = cwd();
-    die "Can't find top-level repository directory"
-        if ($top eq "/");
-}
-chdir($start);
+my $top = `git rev-parse --show-toplevel`;
+chomp($top);
 
 quiet_print "==> Top-level repository dir: $top\n";
 quiet_print "==> Current directory: $start\n";
 
-# Select VCS used to obtain modification info.  Choose in increasing priority
-# order (last hit wins).
-my $vcs;
-$vcs = "git"
-    if (-d "$top/.git");
-$vcs = "hg"
-    if (-d "$top/.hg");
-$vcs = "svn"
-    if (-d "$top/.svn");
-$vcs = "manual"
-    if ("$my_manual_list" ne "");
-
-my @files = find_modified_files($vcs);
+my @files = find_modified_files();
 
 if ($#files < 0) {
     quiet_print "No added / changed files -- nothing to do\n";
@@ -284,98 +266,65 @@ sub quiet_print {
 
 #-------------------------------------------------------------------------------
 
-# Takes two arguments, the top level directory and the VCS method.  Returns a
-# list of file names (relative to pwd) which the VCS considers to be modified.
+# Returns a list of file names (relative to pwd) which git considers
+# to be modified.
 sub find_modified_files {
-    my $vcs = shift;
     my @files = ();
 
-    if ($vcs eq "git") {
-        # Number of path entries to remove from ${top}-relative paths.
-        # (--show-cdup either returns the empty string or sequence of "../"
-        # entries, always ending in a "/")
-        my $n_strip = scalar(split(m!/!, scalar(`git rev-parse --show-cdup`))) - 1;
-
-        # "." restricts scope, but does not get us relative path names
-        my $cmd = "git status -z --porcelain --untracked-files=no .";
-        quiet_print "==> Running: \"$cmd\"\n";
-        my $lines = `$cmd`;
-
-        # From git-status(1):
-        # X          Y     Meaning
-        # -------------------------------------------------
-        #           [MD]   not updated
-        # M        [ MD]   updated in index
-        # A        [ MD]   added to index
-        # D         [ M]   deleted from index
-        # R        [ MD]   renamed in index
-        # C        [ MD]   copied in index
-        # [MARC]           index and work tree matches
-        # [ MARC]     M    work tree changed since index
-        # [ MARC]     D    deleted in work tree
-        # -------------------------------------------------
-        # D           D    unmerged, both deleted
-        # A           U    unmerged, added by us
-        # U           D    unmerged, deleted by them
-        # U           A    unmerged, added by them
-        # D           U    unmerged, deleted by us
-        # A           A    unmerged, both added
-        # U           U    unmerged, both modified
-        # -------------------------------------------------
-        # ?           ?    untracked
-        # -------------------------------------------------
-        foreach my $line (split /\x{00}/, $lines) {
-            my $keep = 0;
-            my ($s1, $s2, $fullname) = $line =~ m/^(.)(.) (.*)$/;
-
-            # ignore all merge cases
-            next if ($s1 eq "D" and $s2 eq "D");
-            next if ($s1 eq "A" and $s2 eq "A");
-            next if ($s1 eq "U" or $s2 eq "U");
-
-            # only update for actually added/modified cases, no copies,
-            # renames, etc.
-            $keep = 1 if ($s1 eq "M" or $s2 eq "M");
-            $keep = 1 if ($s1 eq "A");
-
-            if ($keep) {
-                my $relname = $fullname;
-                $relname =~ s!^([^/]*/){$n_strip}!!g;
-
-                push @files, $relname
-                    if (-f $relname);
-            }
-        }
-    }
-    elsif ($vcs eq "hg" or $vcs eq "svn") {
-        my $cmd = "$vcs st .";
-
-        # Run the command, parsing the output.  Make a list of files that are
-        # added or modified.
-        quiet_print "==> Running: \"$cmd\"\n";
-        open(CMD, "$cmd|") || die "Can't run command";
-        while (<CMD>) {
-            chomp;
-            if ($_ =~ /^M/ || $_ =~ /^A/) {
-                my @tokens = split(/\s+/, $_);
-                # Handle output of both forms:
-                # M       filenameA
-                # A  +    filenameB
-                my $filename = $tokens[1];
-                $filename = $tokens[2]
-                if ($tokens[1] =~ /\+/);
-                # Don't bother saving directory names
-                push(@files, $filename)
-                    if (-f $filename);
-            }
+    # Number of path entries to remove from ${top}-relative paths.
+    # (--show-cdup either returns the empty string or sequence of "../"
+    # entries, always ending in a "/")
+    my $n_strip = scalar(split(m!/!, scalar(`git rev-parse --show-cdup`))) - 1;
+
+    # "." restricts scope, but does not get us relative path names
+    my $cmd = "git status -z --porcelain --untracked-files=no .";
+    quiet_print "==> Running: \"$cmd\"\n";
+    my $lines = `$cmd`;
+
+    # From git-status(1):
+    # X          Y     Meaning
+    # -------------------------------------------------
+    #           [MD]   not updated
+    # M        [ MD]   updated in index
+    # A        [ MD]   added to index
+    # D         [ M]   deleted from index
+    # R        [ MD]   renamed in index
+    # C        [ MD]   copied in index
+    # [MARC]           index and work tree matches
+    # [ MARC]     M    work tree changed since index
+    # [ MARC]     D    deleted in work tree
+    # -------------------------------------------------
+    # D           D    unmerged, both deleted
+    # A           U    unmerged, added by us
+    # U           D    unmerged, deleted by them
+    # U           A    unmerged, added by them
+    # D           U    unmerged, deleted by us
+    # A           A    unmerged, both added
+    # U           U    unmerged, both modified
+    # -------------------------------------------------
+    # ?           ?    untracked
+    # -------------------------------------------------
+    foreach my $line (split /\x{00}/, $lines) {
+        my $keep = 0;
+        my ($s1, $s2, $fullname) = $line =~ m/^(.)(.) (.*)$/;
+
+        # ignore all merge cases
+        next if ($s1 eq "D" and $s2 eq "D");
+        next if ($s1 eq "A" and $s2 eq "A");
+        next if ($s1 eq "U" or $s2 eq "U");
+
+        # only update for actually added/modified cases, no copies,
+        # renames, etc.
+        $keep = 1 if ($s1 eq "M" or $s2 eq "M");
+        $keep = 1 if ($s1 eq "A");
+
+        if ($keep) {
+            my $relname = $fullname;
+            $relname =~ s!^([^/]*/){$n_strip}!!g;
+
+            push @files, $relname
+                if (-f $relname);
         }
-        close(CMD);
-    }
-    elsif ($vcs eq "manual") {
-        @files = split(/\n/, `cat $my_manual_list`);
-    }
-    else {
-        die "unknown VCS '$vcs', stopped";
     }
 
     return @files;