Merge pull request open-mpi#10762 from jsquyres/pr/docs-updates

More docs updates

Author: jsquyres

docs/faq/general-tuning.rst

@@ -27,5 +27,4 @@ that they are worth categorizing in an official way.
    ompio
    macos
 
-   tuning
    general-tuning

docs/faq/index.rst

@@ -154,7 +154,7 @@ as soon as possible.
 
 This parameter can be included in the default MCA parameter file,
 placed in the user's environment, or added to the ``mpirun`` command
-line.  See :ref:`this FAQ entry <faq-tuning-setting-mca-params-label>`
+line.  See :ref:`this FAQ entry <label-running-setting-mca-param-values>`
 for more details on how to set MCA parameters.
 
 /////////////////////////////////////////////////////////////////////////

docs/faq/large-clusters.rst

@@ -235,7 +235,7 @@ perspective.
           value).  The value of ``io_ompio_bytes_per_agg`` could be
           set by system administrators in the system-wide Open MPI
           configuration file, or by users individually. See :ref:`this
-          FAQ item <faq-tuning-setting-mca-params-label>` on setting
+          FAQ item <label-running-setting-mca-param-values>` on setting
           MCA parameters for details.
 
 For more exhaustive tuning of I/O parameters, we recommend the

docs/faq/ompio.rst

@@ -743,8 +743,8 @@ Several notable options are:
   :ref:`this FAQ entry for more details
   <faq-running-mpi-apps-mpirun-host-label>`).
 * ``-n``: Indicate the number of processes to start.
-* ``--mca``: Set MCA parameters (see the :doc:`Run-Time Tuning FAQ
-  category </faq/tuning/>` for more details).
+* ``--mca``: Set MCA parameters (see :ref:`how to set MCA params
+  <label-running-setting-mca-param-values>` for more details).
 * ``--wdir DIRECTORY``: Set the working directory of the started
   applications.  If not supplied, the current working directory is
   assumed (or ``$HOME``, if the current working directory does not
@@ -1320,7 +1320,7 @@ Yes.
 The MCA parameter ``mpi_yield_when_idle`` controls whether an MPI
 process runs in Aggressive or Degraded performance mode.  Setting it
 to 0 forces Aggressive mode; setting it to 1 forces Degraded mode (see
-:ref:`this FAQ entry <faq-tuning-setting-mca-params-label>` to see how
+:ref:`this FAQ entry <label-running-setting-mca-param-values>` to see how
 to set MCA parameters).
 
 Note that this value *only* affects the behavior of MPI processes when

docs/faq/running-mpi-apps.rst

@@ -131,7 +131,9 @@ network at a system level, such that when users invoke ``mpirun`` or
 ``mpiexec`` to launch their jobs, they will automatically only be using
 the network meant for MPI jobs.
 
-:doc:`See the run-time tuning FAQ category </faq/tuning>` for information on how to set global MCA parameters.
+:ref:`See how to set MCA params
+<label-running-setting-mca-param-values>` for information on how to
+set global MCA parameters.
 
 /////////////////////////////////////////////////////////////////////////
 
@@ -161,8 +163,10 @@ I have power users who will want to override my global MCA parameters; is this p
 
 Absolutely.
 
-:doc:`See the run-time tuning FAQ category </faq/tuning>` for information how to set MCA parameters, both at the
-system level and on a per-user (or per-MPI-job) basis.
+:ref:`See how to set MCA params
+<label-running-setting-mca-param-values>` for information how to set
+MCA parameters, both at the system level and on a per-user (or
+per-MPI-job) basis.
 
 /////////////////////////////////////////////////////////////////////////
 

docs/faq/sysadmin.rst

@@ -163,65 +163,65 @@ more MCA parameters, use the ``--level`` command line option.
 EXAMPLES
 --------
 
+Show the default output of options and listing of installed
+components in a human-readable / prettyprint format:
+
 .. code-block::
 
    ompi_info
 
-Show the default output of options and listing of installed
-components in a human-readable / prettyprint format.
+Show the default output of options and listing of installed components
+in a machine-parsable format:
 
 .. code-block::
 
    ompi_info --parsable
 
-Show the default output of options and listing of installed components
-in a machine-parsable format.
+Show the level 1 MCA parameters of the "tcp" BTL component in a
+human-readable / prettyprint format:
 
 .. code-block::
 
    ompi_info --param btl tcp
 
-Show the level 1 MCA parameters of the "tcp" BTL component in a
-human-readable / prettyprint format.
+Show the level 1 through level 6 MCA parameters of the "tcp" BTL
+component in a human-readable / prettyprint format:
 
 .. code-block::
 
    ompi_info --param btl tcp --level 6
 
-Show the level 1 through level 6 MCA parameters of the "tcp" BTL
-component in a human-readable / prettyprint format.
+Show the level 1 MCA parameters of the "tcp" BTL component in a
+machine-parsable format:
 
 .. code-block::
 
    ompi_info --param btl tcp --parsable
 
-Show the level 1 MCA parameters of the "tcp" BTL component in a
-machine-parsable format.
+Show the level 1 through level 3 MCA parameters of string type in a
+human-readable / prettyprint format:
 
 .. code-block::
 
    ompi_info --type string --pretty-print --level 3
 
-Show the level 3 MCA parameters of string type in a human-readable /
-prettyprint format.
+Show the "bindir" that Open MPI was configured with:
 
 .. code-block::
 
    ompi_info --path bindir
 
-Show the "bindir" that Open MPI was configured with.
+Show the version of Open MPI version numbers in a prettyprint format:
 
 .. code-block::
 
    ompi_info --version
 
-Show the version of Open MPI version numbers in a prettyprint format.
+Show *all* information about the Open MPI installation, including all
+components that can be found, all the MCA parameters that they support
+(i.e., levels 1 through 9), versions of Open MPI and the components,
+etc.:
 
 .. code-block::
 
    ompi_info --all
-
-Show *all* information about the Open MPI installation, including all
-components that can be found, all the MCA parameters that they support
-(i.e., levels 1 through 9), versions of Open MPI and the components,
-etc.

docs/faq/tuning.rst

@@ -19,6 +19,7 @@ but they can generally be broken down into two categories:
 
    quickstart
    pmix-and-prrte
+   tuning
 
    localhost
    ssh

docs/man-openmpi/man1/ompi_info.1.rst

@@ -1,3 +1,5 @@
+.. _label-running-role-of-pmix-and-prte:
+
 The role of PMIx and PRRTE
 ==========================