docs: update TCP docs + support deep linking into PMIx and PRTE docs#13599
Merged
jsquyres merged 4 commits intoopen-mpi:mainfrom Jan 14, 2026
Merged
docs: update TCP docs + support deep linking into PMIx and PRTE docs#13599jsquyres merged 4 commits intoopen-mpi:mainfrom
jsquyres merged 4 commits intoopen-mpi:mainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
This PR enhances Open MPI's documentation infrastructure by adding Intersphinx support for deep linking into PMIx and PRRTE documentation, while also updating TCP BTL documentation and fixing the copyright update script.
Key Changes:
- Added Intersphinx extension to enable cross-referencing between Open MPI, PMIx, and PRRTE documentation
- Updated TCP BTL documentation to reference PRRTE/PMIx parameters instead of deprecated OOB TCP parameters
- Fixed
update-my-copyright.plto support Git workspaces and removed Mercurial/Subversion support
Reviewed changes
Copilot reviewed 13 out of 14 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/tuning-apps/networking/tcp.rst | Updated TCP BTL documentation to reference PRRTE/PMIx network configuration parameters |
| docs/requirements.txt | Added sphobjinv dependency for Intersphinx object inventory manipulation |
| docs/mca.rst | Converted plain text references to pmix_info(1) and prte_info(1) into Intersphinx cross-references |
| docs/launching-apps/tm.rst | Converted command references to Intersphinx cross-references for consistency |
| docs/launching-apps/pals.rst | Updated command references to use Intersphinx linking |
| docs/launching-apps/lsf.rst | Updated command references to use Intersphinx linking |
| docs/launching-apps/gridengine.rst | Updated command references to use Intersphinx linking |
| docs/conf.py | Implemented Intersphinx mapping configuration with dynamic inventory generation for internal PMIx/PRRTE |
| docs/Makefile.am | Added environment variables to Sphinx build commands for Intersphinx configuration |
| contrib/update-my-copyright.pl | Simplified script to use only Git, removing Mercurial/Subversion support |
| config/opal_config_pmix.m4 | Added logic to determine and export PMIx documentation URL base |
| config/ompi_setup_prrte.m4 | Added logic to determine and export PRRTE documentation URL base |
| 3rd-party/prrte | Updated submodule pointer to include PRRTE documentation changes |
| .gitignore | Added pattern to ignore generated Intersphinx inventory files |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
jsquyres
force-pushed
the
pr/tcp-docs-updates
branch
3 times, most recently
from
d70097f to
759bbca
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 13 out of 14 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (2)
docs/conf.py:1
- The comment states this is setting up internal PMIx docs, but the actual value being set is for OMPI_PRRTE_DOCS_URL_BASE (PRRTE). The URL path should be '../../pmix/html' for PMIx context, not PRRTE. This appears to be in the wrong conditional block - it should be in the PMIx section around line 312, not the PRRTE comment context.
# Configuration file for the Sphinx documentation builder.
docs/conf.py:1
- Comment mentions 'external PRRTE docs URL' but this is in the PMIx configuration section (based on the surrounding context at line 301). Should reference 'external PMIx docs URL' instead.
# Configuration file for the Sphinx documentation builder.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
jsquyres
force-pushed
the
pr/tcp-docs-updates
branch
5 times, most recently
from
2834e73 to
bc928da
Compare
hppritcha
previously approved these changes
Jan 5, 2026
Member
|
@jsquyres I finally got the AMIs updated, and there is a real build failure. It looks like a file is getting left behind after a step in |
Don't search for a .git directory; it might not exist. Also, remove unnecessary Mercurial and Subversion support; we haven't used these for years. Signed-off-by: Jeff Squyres <jeff@squyres.com>
Signed-off-by: Jeff Squyres <jeff@squyres.com> Signed-off-by: Howard Pritchard <howardp@lanl.gov>
Use Intersphinx (https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) for making links out to PMIx and PRTE docs. If we simply always linked against the https/internet PMIx and PRTE docs, Intersphinx makes this very easy. But that's not the Open MPI way! Instead, we want to support linking against the internal (embedded) PMIx and PRTE docs when relevant and possible, mainly to support fully-offline HTML docs (e.g., for those who operated in not-connected-to-the-internet scenarios). As such, there's several cases that need to be handled properly: 1. When building the internal PMIx / PRTE, link to the local instances of those docs (vs. the https/internet instance). Ensure to use relative paths (vs. absolute paths) so that the pre-built HTML docs that we include in OMPI distribution tarballs work, regardless of the --prefix/etc. used at configure time. NOTE: When the Open MPI Sphinx docs are built, we have not yet installed the PMIx / PRTE docs. So create our own (fake) objects.inv inventory file for where the PMIx / PRTE docs *will* be installed so that Intersphinx can do its deep linking properly. At least for now, we only care about deep links for pmix_info(1) and prte_info(1), so we can just hard-code those into those inventory files and that's good enough. If the OMPI docs link more deeply into the PMIx / PRTE docs someday (i.e., link to a bunch more things than just pmix_info(1) / prte_info(1)), we might need to revisit this design decision. 2. When building against an external PMIx / PRTE, make a best guess as to where their local HTML doc instance may be (namely: $project_prefix/share/doc/PROJECT). Don't try to handle all the possibilities -- it just gets even more complicated than this already is. If we can't find it, just link out to the https/internet docs. Other miscellaneous small changes: * Added another Python module in docs/requirements.txt (for building the Sphinx inventory file). * Use slightly-more-pythonix dict.get() API calls in docs/conf.py for simplicity. * Updated OMPI PRTE submodule pointer to get a prte_info.1.rst label update that works for both upstream PRTE and the OMPI PRTE fork. Signed-off-by: Jeff Squyres <jeff@squyres.com>
Per the prior commit, update all OMPI docs RST to properly link to PMIx and PRTE documentation. Also added a few mpirun(1) links because they were in the vicinity of the pmix_info(1) and prte_info(1) that were being updates. Signed-off-by: Jeff Squyres <jeff@squyres.com>
jsquyres
force-pushed
the
pr/tcp-docs-updates
branch
from
bc928da to
5b799a0
Compare
Member
Author
|
CI failure is that the new Python module was added to all the relevant CI AMIs except RHEL 8. We're adding it now -- will take a few hours to build the new AMI, and then we can re-run CI. |
rhc54
added a commit
to rhc54/prrte
that referenced
this pull request
Jan 13, 2026
Ported from an OMPI contribution by Jeff Squyres (part of open-mpi/ompi#13599): ```text update-my-copyright.py: properly support git workspaces Don't search for a .git directory; it might not exist. Also, remove unnecessary Mercurial and Subversion support; we haven't used these for years. ``` Signed-off-by: Ralph Castain <rhc@pmix.org>
rhc54
added a commit
to openpmix/prrte
that referenced
this pull request
Jan 13, 2026
Ported from an OMPI contribution by Jeff Squyres (part of open-mpi/ompi#13599): ```text update-my-copyright.py: properly support git workspaces Don't search for a .git directory; it might not exist. Also, remove unnecessary Mercurial and Subversion support; we haven't used these for years. ``` Signed-off-by: Ralph Castain <rhc@pmix.org>
hppritcha
approved these changes
Jan 13, 2026
This was referenced Jan 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR replaces PR #13584 (some minor TCP BTL docs updates), but also adds a lot more. See individual commit messages for details, but here's the short version:
update-my-copyright.plto properly support Git workspaces and also remove support for Mercurial and Subversion.pmix_info(1)andprte_info(1)in OMPI's RST docs to deep link into their respective docs.