Include PRTE RST content in mpirun.1 man page #11820
Merged
Conversation
This file contains 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
jsquyres
force-pushed
the
pr/generate-mpirun-man-page
branch
from
db297d2
to
a65f248
Compare
|
For those who would like to try this themselves, you will need to update your PRRTE git submodule pointer to point to the branch for the corresponding PRRTE PR openpmix/prrte#1765: Then you should be able to go back up to the OMPI git clone root and autogen / build from there (ensure that Sphinx is in your path yadda yadda yadda). |
jsquyres
force-pushed
the
pr/generate-mpirun-man-page
branch
from
2fb4cf5
to
1027c0c
Compare
jsquyres
commented
Sep 9, 2023
jsquyres
force-pushed
the
pr/generate-mpirun-man-page
branch
4 times, most recently
from
d15bcde
to
67bec85
Compare
|
@bwbarrett This PR is ready for review. |
|
As this PR got more mature, it created a lot of new configury cases. This spreadsheet shows all 32 new cases. |
Could you please open access to the spreadsheet? |
Done. |
jsquyres
force-pushed
the
pr/generate-mpirun-man-page
branch
from
67bec85
to
29d2ec1
Compare
|
Only change from the force push a few minutes ago was updating the PRRTE submodule pointer to include Ralph's feedback on openpmix/prrte#1788. |
|
jsquyres
force-pushed
the
pr/generate-mpirun-man-page
branch
from
29d2ec1
to
27f7ea2
Compare
|
Moving this back to draft 😦 There's at least a few problems that need fixing:
|
Signed-off-by: Jeff Squyres <[email protected]>
Signed-off-by: Jeff Squyres <[email protected]>
This commit introduce a fundamentally new concept: have configure search PRRTE for RST files to include in Open MPI's documentation (regardless of whether we're using the internal/bundled PRRTE or an external PRRTE). If we're building against an external PRRTE that is old enough that it doesn't have any RST files installed, we'll make up some dummy RST files that basically say "you don't get help/content here because your PRRTE is too old." To simplify the configury for this scheme, this commit also makes another change: the pre-built HTML docs and nroff man pages included in distribution tarballs are now located at docs/html/ and docs/man/, respectively (vs. the location where we'll build them: docs/_build/html/ and docs/_build/man/, respectively). There are two cases here: 1. If the user has Sphinx available, we'll build the docs under docs/_build/, and install those (effectively ignoring the pre-built docs). 2. If the user does not have Sphinx available, we'll just install the pre-built docs. This simplified things like "make clean" and "make distcheck". Including RST content from PRTE required another major change: when we build the RST docs in a VPATH scenario, we copy the entire docs/ source tree to the build tree. This allows us to modify the RST sources a bit (e.g., to include the PRRTE RST files or generate dummy PRRTE RST files). mpirun.1.rst is updated to include the RST content from PRRTE about CLI options. More work needs to be done here to remove old, now-redundant content. Finally, we also amend the advice to implementors to have Sphinx installed when building their package so that Open MPI's build system can properly slurp in their PRRTE's RST docs. Signed-off-by: Jeff Squyres <[email protected]>
jsquyres
force-pushed
the
pr/generate-mpirun-man-page
branch
from
5683ede
to
75d1a24
Compare
Since RTD doesn't run autogen, configure, or make, we now have to manually copy a few RST files from the embedded PRRTE to the docs/ tree before RTD invokes Sphinx. Signed-off-by: Jeff Squyres <[email protected]>
jsquyres
force-pushed
the
pr/generate-mpirun-man-page
branch
from
75d1a24
to
c356981
Compare
|
All known problems fixed, and intermediate git commits squashed appropriately. Also incorporated |
bwbarrett
approved these changes
Sep 25, 2023
|
All regression testing passed. Merging. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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 is in conjunction with openpmix/prrte#1765. The intent is to use RST content from PRTE to fill out Open MPI's
mpirun.1man page (and corresponding HTML rendering).The exact mechanism and scheme for this has changed a few times over the course of experimenting / development, so I won't comment too much on it here. This PR will likely contain a whole truckload of WIP / ugly commits until we get everything working. At the end, we'll squash and make it pretty / make the git commit messages be accurate / all the things.
As this PR got more mature, it created a lot of new configury cases. This spreadsheet shows all 32 new cases.