docs: move more content out of the FAQ

jsquyres · jsquyres · commit 6acc2c28beed · 2022-09-06T17:23:31.000-04:00
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 &lt;jsquyres@cisco.com&gt;
diff --git a/docs/faq/general-tuning.rst b/docs/faq/general-tuning.rst
diff --git a/docs/faq/index.rst b/docs/faq/index.rst
@@ -27,5 +27,4 @@ that they are worth categorizing in an official way.
    ompio
    macos
 
-   tuning
    general-tuning
diff --git a/docs/faq/large-clusters.rst b/docs/faq/large-clusters.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.
 
 /////////////////////////////////////////////////////////////////////////
diff --git a/docs/faq/ompio.rst b/docs/faq/ompio.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
diff --git a/docs/faq/running-mpi-apps.rst b/docs/faq/running-mpi-apps.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
diff --git a/docs/faq/sysadmin.rst b/docs/faq/sysadmin.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.
 
 /////////////////////////////////////////////////////////////////////////
 
diff --git a/docs/man-openmpi/man1/ompi_info.1.rst b/docs/man-openmpi/man1/ompi_info.1.rst
@@ -198,8 +198,8 @@ machine-parsable format:
 
    ompi_info --param btl tcp --parsable
 
-Show the level 3 MCA parameters of string type in a human-readable /
-prettyprint format:
+Show the level 1 through level 3 MCA parameters of string type in a
+human-readable / prettyprint format:
 
 .. code-block::
 
diff --git a/docs/running-apps/index.rst b/docs/running-apps/index.rst
@@ -19,6 +19,7 @@ but they can generally be broken down into two categories:
 
    quickstart
    pmix-and-prrte
+   tuning
 
    localhost
    ssh
diff --git a/docs/running-apps/pmix-and-prrte.rst b/docs/running-apps/pmix-and-prrte.rst
@@ -1,3 +1,5 @@
+.. _label-running-role-of-pmix-and-prte:
+
 The role of PMIx and PRRTE
 ==========================
 
diff --git a/docs/running-apps/tuning.rst b/docs/running-apps/tuning.rst

-Original file line number
+Diff line change
    ompio
    macos
 -   tuning
    general-tuning
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _label-running-role-of-pmix-and-prte:`
	`2`	`+`
`1`	`3`	`The role of PMIx and PRRTE`
`2`	`4`	`==========================`
`3`	`5`