v5.0.x: docs updates #10772

jsquyres · 2022-09-07T01:47:01Z

This is the v5.0.x version of #10762.

I'm going to wait until #10771 merges so that I can add it to this PR, and get all those commits in a single PR to v5.0.x.
EDIT: #10771 has been merged, and the commits have been added to this PR.

Trivial change: put the explanation text *before* the example. Signed-off-by: Jeff Squyres <jsquyres@cisco.com> (cherry picked from commit 97f848d)

This file was a placeholder and did not contain any useful content, anyway. Signed-off-by: Jeff Squyres <jsquyres@cisco.com> (cherry picked from commit 9bdbe93)

Moved a bunch of MCA-related content out of faq/general-tuning to a new file in running-apps/tuning.rst. Removed AMCA documentation because that functionality has morphed into the "--tuned" functionality. Indeed, the --am CLI parameter is silently converted to --tuned. Signed-off-by: Jeff Squyres <jsquyres@cisco.com> (cherry picked from commit 6acc2c2)

jsquyres · 2022-09-07T03:30:13Z

bot:aws:recheck

gpaulsen · 2022-09-07T13:43:51Z

docs/faq/general-tuning.rst

@@ -638,7 +162,8 @@ the ``mpi_warn_on_fork`` MCA parameter.  For example:
   shell$ mpirun --mca mpi_warn_on_fork 0 ...

 Of course, systems that ``dlopen("libmpi.so", ...)`` may not use Open
-MPI's ``mpirun``, and therefore may need to use :ref:`a different
+MPI's ``mpirun``, and therefore may need to use (JMS: this ref no


Jeff, are you okay merging this into v5.0.x on the assumption that we WILL fixup all of these references before we ship? or would it be better to address now?

This is in the FAQ section of the doc, and is destined to go away -- that's why I didn't bother fixing up the ref here.

gpaulsen · 2022-09-07T13:49:21Z

docs/running-apps/tuning.rst

+          See :ref:`the role of PMIx and PRRTE
+          <label-running-role-of-pmix-and-prte>` for more information.
+
+Frameworks


Would this be the appropriate place to discuss how both Open MPI project, along with the PMIx project and the PRRTE project all have individual MCA frameworks?

You mean more than https://docs.open-mpi.org/en/main/running-apps/pmix-and-prrte.html?

gpaulsen · 2022-09-07T13:50:46Z

docs/running-apps/tuning.rst

+not all of them may be present or available on your system.  You can
+use the :ref:`ompi_info(1) <man1-ompi_info>` command to see what
+components are included in Open MPI |ompi_ver| on your system.
+


If we include discussion about other MCA frameworks, we could also mention pmix_info(1) and prrte_info() briefly here.

Yes, if we mention that PMIx and PRTE have MCA frameworks of their own (e.g., an in Attention box or something), we could also mention pmix_info and prte_info in another Attention box here, or something).

We'd need to make a new PR to main about this.

Yeah, I've been thinking about that - users are going to confront a 3-headed world where they do need to know what the various layers do and how they can be directed. You might need a little overview somewhere so they can visualize it.

* Removed a bunch of redundant text and replaced it with links to elsewhere in the docs. * Added developer-level rules of thumb for levels 1-9 of MCA params. * Added code style documentation; consolidated this and "source code tree layout" into a single source-code.rst file. Signed-off-by: Jeff Squyres <jsquyres@cisco.com> (cherry picked from commit 67473fc)

Note on the front page that the v5.0.0 docs are on the public web site, in the tarball, and installed locally. Signed-off-by: Jeff Squyres <jsquyres@cisco.com> (cherry picked from commit f33d3d4)

jsquyres · 2022-09-07T18:49:21Z

@gpaulsen @rhc54 I think those points are valid; I'll make another PR on main about them. I think this PR is fine to merge as-is; the docs are an evolving / living document... 😄 ✏️ 👓

jsquyres · 2022-09-07T19:28:06Z

bot:aws:retest

Signed-off-by: Thomas Naughton <naughtont@ornl.gov> Co-authored-by: Jeff Squyres <jsquyres@users.noreply.github.com> (cherry picked from commit 01ac437)

jsquyres · 2022-09-09T19:21:34Z

bot:aws:retest

awlauria · 2022-09-09T21:45:33Z

@gpaulsen @rhc54 I think those points are valid; I'll make another PR on main about them. I think this PR is fine to merge as-is; the docs are an evolving / living document... smile pencil2 eyeglasses

Approving and merging based on this.

@jolivain

* Typo fixes * Add :ref: links to man pages (mostly `mpirun` and `ompi_info`) * Add notes for contributors about PR'ing to `main` first and then cherry-picking to release branches later. Thanks to @jolivain suggesting that we add this policy to the docs. * Include contributor suggestion to submit fixes to the docs. * Renamed Developers -> Git to "GitHub, Git, and related topics". Added info about: * Git commits and a reference to the contributors declaration (in contributors.rst) * Branching scheme * Details about PR to main first and cherry-picking to release branches * A few words about Github PR CI / MTT * Added information about running Sphinx, and how to view the Sphinx docs locally * Added notes about how to view man pages locally * Added a placeholder oshrun.1 man page (it just refers to mpirun.1) * Per open-mpi#10772 (comment), discuss PMIx and PRRTE MCA Signed-off-by: Jeff Squyres <jsquyres@cisco.com>

@jolivain

* Typo fixes * Add :ref: links to man pages (mostly `mpirun` and `ompi_info`) * Add notes for contributors about PR'ing to `main` first and then cherry-picking to release branches later. Thanks to @jolivain suggesting that we add this policy to the docs. * Include contributor suggestion to submit fixes to the docs. * Renamed Developers -> Git to "GitHub, Git, and related topics". Added info about: * Git commits and a reference to the contributors declaration (in contributors.rst) * Branching scheme * Details about PR to main first and cherry-picking to release branches * A few words about Github PR CI / MTT * Added information about running Sphinx, and how to view the Sphinx docs locally * Added notes about how to view man pages locally * Added a placeholder oshrun.1 man page (it just refers to mpirun.1) * Per open-mpi#10772 (comment), discuss PMIx and PRRTE MCA * Mention Perl and Python as tools required by Open MPI developers * Add some advice for downstream packagers: * Don't use Open MPI's bundled sub-packages (Libevent, Hwloc, PMIx, PRTE) * Discussion of components: included in project libraries vs. DSOs * Add short "prerequisites" section for running MPI apps Signed-off-by: Jeff Squyres <jsquyres@cisco.com>

@jolivain

* Typo fixes * Add :ref: links to man pages (mostly `mpirun` and `ompi_info`) * Add notes for contributors about PR'ing to `main` first and then cherry-picking to release branches later. Thanks to @jolivain suggesting that we add this policy to the docs. * Include contributor suggestion to submit fixes to the docs. * Renamed Developers -> Git to "GitHub, Git, and related topics". Added info about: * Git commits and a reference to the contributors declaration (in contributors.rst) * Branching scheme * Details about PR to main first and cherry-picking to release branches * A few words about Github PR CI / MTT * Added information about running Sphinx, and how to view the Sphinx docs locally * Added notes about how to view man pages locally * Added a placeholder oshrun.1 man page (it just refers to mpirun.1) * Per open-mpi#10772 (comment), discuss PMIx and PRRTE MCA * Mention Perl and Python as tools required by Open MPI developers * Expanded on some "advice for packagers" from the "required support dependencies" section, and moved it to its own section: * Don't use Open MPI's bundled sub-packages (Libevent, Hwloc, PMIx, PRTE) * Discussion of components: included in project libraries vs. DSOs * Add short "prerequisites" section for running MPI apps Signed-off-by: Jeff Squyres <jsquyres@cisco.com>

@jolivain

* Typo fixes * Add :ref: links to man pages (mostly `mpirun` and `ompi_info`) * Add notes for contributors about PR'ing to `main` first and then cherry-picking to release branches later. Thanks to @jolivain suggesting that we add this policy to the docs. * Include contributor suggestion to submit fixes to the docs. * Renamed Developers -> Git to "GitHub, Git, and related topics". Added info about: * Git commits and a reference to the contributors declaration (in contributors.rst) * Branching scheme * Details about PR to main first and cherry-picking to release branches * A few words about Github PR CI / MTT * Added information about running Sphinx, and how to view the Sphinx docs locally * Added notes about how to view man pages locally * Added a placeholder oshrun.1 man page (it just refers to mpirun.1) * Per open-mpi#10772 (comment), discuss PMIx and PRRTE MCA * Mention Perl and Python as tools required by Open MPI developers * Expanded on some "advice for packagers" from the "required support dependencies" section, and moved it to its own section: * Don't use Open MPI's bundled sub-packages (Libevent, Hwloc, PMIx, PRTE) * Discussion of components: included in project libraries vs. DSOs * Add short "prerequisites" section for running MPI apps Signed-off-by: Jeff Squyres <jsquyres@cisco.com>

@jolivain

* Typo fixes * Add :ref: links to man pages (mostly `mpirun` and `ompi_info`) * Add notes for contributors about PR'ing to `main` first and then cherry-picking to release branches later. Thanks to @jolivain suggesting that we add this policy to the docs. * Include contributor suggestion to submit fixes to the docs. * Renamed Developers -> Git to "GitHub, Git, and related topics". Added info about: * Git commits and a reference to the contributors declaration (in contributors.rst) * Branching scheme * Details about PR to main first and cherry-picking to release branches * A few words about Github PR CI / MTT * Added information about running Sphinx, and how to view the Sphinx docs locally * Added notes about how to view man pages locally * Added a placeholder oshrun.1 man page (it just refers to mpirun.1) * Per open-mpi#10772 (comment), discuss PMIx and PRRTE MCA * Mention Perl and Python as tools required by Open MPI developers * Expanded on some "advice for packagers" from the "required support dependencies" section, and moved it to its own section: * Don't use Open MPI's bundled sub-packages (Libevent, Hwloc, PMIx, PRTE) * Discussion of components: included in project libraries vs. DSOs * Add short "prerequisites" section for running MPI apps Signed-off-by: Jeff Squyres <jsquyres@cisco.com>

@jolivain

* Typo fixes * Add :ref: links to man pages (mostly `mpirun` and `ompi_info`) * Add notes for contributors about PR'ing to `main` first and then cherry-picking to release branches later. Thanks to @jolivain suggesting that we add this policy to the docs. * Include contributor suggestion to submit fixes to the docs. * Renamed Developers -> Git to "GitHub, Git, and related topics". Added info about: * Git commits and a reference to the contributors declaration (in contributors.rst) * Branching scheme * Details about PR to main first and cherry-picking to release branches * A few words about Github PR CI / MTT * Added information about running Sphinx, and how to view the Sphinx docs locally * Added notes about how to view man pages locally * Added a placeholder oshrun.1 man page (it just refers to mpirun.1) * Per open-mpi#10772 (comment), discuss PMIx and PRRTE MCA * Mention Perl and Python as tools required by Open MPI developers * Expanded on some "advice for packagers" from the "required support dependencies" section, and moved it to its own section: * Don't use Open MPI's bundled sub-packages (Libevent, Hwloc, PMIx, PRTE) * Discussion of components: included in project libraries vs. DSOs * Add short "prerequisites" section for running MPI apps Signed-off-by: Jeff Squyres <jsquyres@cisco.com>

@jolivain

* Typo fixes * Add :ref: links to man pages (mostly `mpirun` and `ompi_info`) * Add notes for contributors about PR'ing to `main` first and then cherry-picking to release branches later. Thanks to @jolivain suggesting that we add this policy to the docs. * Include contributor suggestion to submit fixes to the docs. * Renamed Developers -> Git to "GitHub, Git, and related topics". Added info about: * Git commits and a reference to the contributors declaration (in contributors.rst) * Branching scheme * Details about PR to main first and cherry-picking to release branches * A few words about Github PR CI / MTT * Added information about running Sphinx, and how to view the Sphinx docs locally * Added notes about how to view man pages locally * Added a placeholder oshrun.1 man page (it just refers to mpirun.1) * Per open-mpi#10772 (comment), discuss PMIx and PRRTE MCA * Mention Perl and Python as tools required by Open MPI developers * Expanded on some "advice for packagers" from the "required support dependencies" section, and moved it to its own section: * Don't use Open MPI's bundled sub-packages (Libevent, Hwloc, PMIx, PRTE) * Discussion of components: included in project libraries vs. DSOs * Add short "prerequisites" section for running MPI apps Signed-off-by: Jeff Squyres <jsquyres@cisco.com> (cherry picked from commit 061f908)

@jolivain

* Typo fixes * Add :ref: links to man pages (mostly `mpirun` and `ompi_info`) * Add notes for contributors about PR'ing to `main` first and then cherry-picking to release branches later. Thanks to @jolivain suggesting that we add this policy to the docs. * Include contributor suggestion to submit fixes to the docs. * Renamed Developers -> Git to "GitHub, Git, and related topics". Added info about: * Git commits and a reference to the contributors declaration (in contributors.rst) * Branching scheme * Details about PR to main first and cherry-picking to release branches * A few words about Github PR CI / MTT * Added information about running Sphinx, and how to view the Sphinx docs locally * Added notes about how to view man pages locally * Added a placeholder oshrun.1 man page (it just refers to mpirun.1) * Per open-mpi#10772 (comment), discuss PMIx and PRRTE MCA * Mention Perl and Python as tools required by Open MPI developers * Expanded on some "advice for packagers" from the "required support dependencies" section, and moved it to its own section: * Don't use Open MPI's bundled sub-packages (Libevent, Hwloc, PMIx, PRTE) * Discussion of components: included in project libraries vs. DSOs * Add short "prerequisites" section for running MPI apps Signed-off-by: Jeff Squyres <jsquyres@cisco.com>

jsquyres added documentation Target: v5.0.x labels Sep 7, 2022

jsquyres added this to the v5.0.0 milestone Sep 7, 2022

jsquyres added 3 commits September 6, 2022 21:56

ompi_info.1: switch order of text/example

e0e7a07

Trivial change: put the explanation text *before* the example. Signed-off-by: Jeff Squyres <jsquyres@cisco.com> (cherry picked from commit 97f848d)

docs: remove empty placeholder file

1cc73c1

This file was a placeholder and did not contain any useful content, anyway. Signed-off-by: Jeff Squyres <jsquyres@cisco.com> (cherry picked from commit 9bdbe93)

jsquyres force-pushed the pr/v5.0.x/docs-updates branch from b2c056e to 40685d3 Compare September 7, 2022 01:56

gpaulsen reviewed Sep 7, 2022

View reviewed changes

jsquyres added 2 commits September 7, 2022 14:47

docs: update 5.0.0 doc locations

86eee66

Note on the front page that the v5.0.0 docs are on the public web site, in the tarball, and installed locally. Signed-off-by: Jeff Squyres <jsquyres@cisco.com> (cherry picked from commit f33d3d4)

jsquyres marked this pull request as ready for review September 7, 2022 18:48

jsquyres requested a review from gpaulsen September 7, 2022 19:33

This was referenced Sep 8, 2022

starter text for declspec description #10770

Closed

add text on symbol visibility jsquyres/ompi#11

Closed

add text on symbol visibility

5840d48

Signed-off-by: Thomas Naughton <naughtont@ornl.gov> Co-authored-by: Jeff Squyres <jsquyres@users.noreply.github.com> (cherry picked from commit 01ac437)

jsquyres mentioned this pull request Sep 9, 2022

add text on symbol visibility #10780

Merged

jsquyres requested review from jjhursey and naughtont3 September 9, 2022 15:21

awlauria approved these changes Sep 9, 2022

View reviewed changes

awlauria merged commit 30ae351 into open-mpi:v5.0.x Sep 9, 2022

jsquyres deleted the pr/v5.0.x/docs-updates branch September 9, 2022 21:57

jsquyres mentioned this pull request Sep 12, 2022

A variety of docs updates #10793

Merged

jsquyres mentioned this pull request Sep 23, 2022

v5.0: A variety of docs updates #10838

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

v5.0.x: docs updates #10772

v5.0.x: docs updates #10772

Uh oh!

jsquyres commented Sep 7, 2022 •

edited

Loading

Uh oh!

jsquyres commented Sep 7, 2022

Uh oh!

gpaulsen Sep 7, 2022

Uh oh!

jsquyres Sep 7, 2022

Uh oh!

gpaulsen Sep 7, 2022

Uh oh!

jsquyres Sep 7, 2022

Uh oh!

gpaulsen Sep 7, 2022

Uh oh!

jsquyres Sep 7, 2022

Uh oh!

rhc54 Sep 7, 2022

Uh oh!

jsquyres commented Sep 7, 2022

Uh oh!

jsquyres commented Sep 7, 2022

Uh oh!

jsquyres commented Sep 9, 2022

Uh oh!

awlauria commented Sep 9, 2022

Uh oh!

Uh oh!

v5.0.x: docs updates #10772

v5.0.x: docs updates #10772

Uh oh!

Conversation

jsquyres commented Sep 7, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jsquyres commented Sep 7, 2022

Uh oh!

gpaulsen Sep 7, 2022

Choose a reason for hiding this comment

Uh oh!

jsquyres Sep 7, 2022

Choose a reason for hiding this comment

Uh oh!

gpaulsen Sep 7, 2022

Choose a reason for hiding this comment

Uh oh!

jsquyres Sep 7, 2022

Choose a reason for hiding this comment

Uh oh!

gpaulsen Sep 7, 2022

Choose a reason for hiding this comment

Uh oh!

jsquyres Sep 7, 2022

Choose a reason for hiding this comment

Uh oh!

rhc54 Sep 7, 2022

Choose a reason for hiding this comment

Uh oh!

jsquyres commented Sep 7, 2022

Uh oh!

jsquyres commented Sep 7, 2022

Uh oh!

jsquyres commented Sep 9, 2022

Uh oh!

awlauria commented Sep 9, 2022

Uh oh!

Uh oh!

jsquyres commented Sep 7, 2022 •

edited

Loading