Merge pull request open-mpi#11367 from zerothi/11340-doc-beautification

Beautification of rst documentation

Author: jsquyres

docs/conf.py

@@ -116,7 +116,11 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 import sphinx_rtd_theme
-extensions = ['recommonmark', "sphinx_rtd_theme"]
+extensions = [
+    'recommonmark',
+    "sphinx_rtd_theme",
+    "sphinx.ext.extlinks",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -139,6 +143,14 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 #html_static_path = ['_static']
 
+
+# Short hand external links
+# Allows smoother transitioning for commonly used articles and sites
+extlinks = {
+    'doi': ('https://doi.org/%s', '%s'),
+}
+
+
 # -- Options for MAN output -------------------------------------------------
 
 import os

docs/features/ulfm.rst

@@ -107,7 +107,7 @@ please use:
     J. Dongarra: Post-failure recovery of MPI communication
     capability: Design and rationale. IJHPCA 27(3): 244-254 (2013).*
 
-Available from: https://journals.sagepub.com/doi/10.1177/1094342013488238.
+Available from: :doi:`10.1177/1094342013488238`.
 
 Building ULFM support in Open MPI
 ---------------------------------

docs/man-openmpi/man3/ERRORS.rst

@@ -6,47 +6,41 @@ with the communication object (e.g., communicator, window, file) is called.
 If no communication object is associated with the MPI call, then the call is
 considered attached to MPI_COMM_SELF and will call the associated MPI error
 handler. When MPI_COMM_SELF is not initialized (i.e., before
-MPI_INIT / MPI_INIT_THREAD, after MPI_FINALIZE, or when using the Sessions
+:ref:`MPI_Init`/:ref:`MPI_Init_thread`, after :ref:`MPI_Finalize`, or when using the Sessions
 Model exclusively) the error raises the initial error handler. The initial
-error handler can be changed by calling MPI_COMM_SET_ERRHANDLER on
+error handler can be changed by calling :ref:`MPI_Comm_set_errhandler` on
 MPI_COMM_SELF when using the World model, or the mpi_initial_errhandler CLI
-argument to mpiexec or info key to MPI_COMM_SPAWN[_MULTIPLE].
+argument to mpiexec or info key to :ref:`MPI_Comm_spawn`/:ref:`MPI_Comm_spawn_multiple`.
 If no other appropriate error handler has been set, then the MPI_ERRORS_RETURN
 error handler is called for MPI I/O functions and the MPI_ERRORS_ABORT error
 handler is called for all other MPI functions.
 
-In the sessions model, the error handler can be set during MPI_Session_init.
+Open MPI includes three predefined error handlers that can be used:
 
-Open MPI includes three predefined error handlers that can be used::
+* ``MPI_ERRORS_ARE_FATAL``
+  Causes the program to abort all connected MPI processes.
+* ``MPI_ERRORS_ABORT``
+  An error handler that can be invoked on a communicator,
+  window, file, or session. When called on a communicator, it
+  acts as if :ref:`MPI_Abort` was called on that communicator. If
+  called on a window or file, acts as if :ref:`MPI_Abort` was called
+  on a communicator containing the group of processes in the
+  corresponding window or file. If called on a session,
+  aborts only the local process.
+* ``MPI_ERRORS_RETURN``
+  Returns an error code to the application.
 
- MPI_ERRORS_ARE_FATAL: Causes the program to abort all connected MPI processes.
- MPI_ERRORS_ABORT:     An error handler that can be invoked on a communicator,
-                       window, file, or session. When called on a communicator, it
-                       acts as if MPI_ABORT was called on that communicator. If
-                       called on a window or file, acts as if MPI_ABORT was called
-                       on a communicator containing the group of processes in the
-                       corresponding window or file. If called on a session,
-                       aborts only the local process.
- MPI_ERRORS_RETURN:    Returns an error code to the application.
+MPI applications can also implement their own error handlers by calling:
 
-MPI applications can also implement their own error handlers.
-
-Custom MPI error handlers can be created by calling:
-:ref:`MPI_Comm_create_errhandler(3) <MPI_Comm_create_errhandler>`
-:ref:`MPI_File_create_errhandler(3) <MPI_File_create_errhandler>`
-:ref:`MPI_Session_create_errhandler(3) <MPI_Session_create_errhandler>`
-:ref:`MPI_Win_create_errhandler(3) <MPI_Win_create_errhandler>`
-
-Predefined and custom error handlers can be set by calling:
-:ref:`MPI_Comm_set_errhandler(3) <MPI_Comm_set_errhandler>`
-:ref:`MPI_File_set_errhandler(3) <MPI_File_set_errhandler>`
-:ref:`MPI_Session_set_errhandler(3) <MPI_Session_set_errhandler>`
-:ref:`MPI_Win_set_errhandler(3) <MPI_Win_set_errhandler>`
+* :ref:`MPI_Comm_create_errhandler` then :ref:`MPI_Comm_set_errhandler`
+* :ref:`MPI_File_create_errhandler` then :ref:`MPI_File_set_errhandler`
+* :ref:`MPI_Session_create_errhandler` then :ref:`MPI_Session_set_errhandler` or at :ref:`MPI_Session_init`
+* :ref:`MPI_Win_create_errhandler` then :ref:`MPI_Win_set_errhandler`
 
 Note that MPI does not guarantee that an MPI program can continue past
 an error.
 
-See the MPI man page for a full list of MPI error codes.
+See the :ref:`MPI man page <open-mpi>` for a full list of :ref:`MPI error codes <open-mpi-errors>`.
 
 See the Error Handling section of the MPI-|mpi_standard_version| standard for
 more information.

docs/man-openmpi/man3/MPIX_Query_cuda_support.3.rst

@@ -94,4 +94,4 @@ EXAMPLES
    }
 
 .. seealso::
-   :ref:`MPIX_Query_rocm_support`
+   * :ref:`MPIX_Query_rocm_support`

docs/man-openmpi/man3/MPIX_Query_rocm_support.3.rst

@@ -94,4 +94,4 @@ EXAMPLES
    }
 
 .. seealso::
-   :ref:`MPIX_Query_cuda_support`
+   * :ref:`MPIX_Query_cuda_support`

docs/man-openmpi/man3/MPI_Abort.3.rst

@@ -53,7 +53,7 @@ INPUT PARAMETERS
 
 OUTPUT PARAMETER
 ----------------
-* ``IERROR``: Fortran only: Error status (integer).
+* ``ierror``: Fortran only: Error status (integer).
 
 DESCRIPTION
 -----------
@@ -67,9 +67,9 @@ abort (errorcode).
 The long-term goal of the Open MPI implementation is to terminate all
 processes in all tasks that contain a process in *comm, and the error
 code is not returned to the invoking environment. At the moment, this
-isn't fully implemented and :ref:`MPI_Abort` will terminate the entire job.*
+isn't fully implemented and* :ref:`MPI_Abort` *will terminate the entire job.*
 
-Note: All associated processes are sent a SIGTERM.
+Note: All associated processes are sent a ``SIGTERM``.
 
 
 ERRORS

docs/man-openmpi/man3/MPI_Accumulate.3.rst

@@ -99,7 +99,7 @@ INPUT PARAMETERS
 OUTPUT PARAMETER
 ----------------
 * ``MPI_Raccumulate``:  RMA request
-* ``IERROR``: Fortran only: Error status (integer).
+* ``ierror``: Fortran only: Error status (integer).
 
 DESCRIPTION
 -----------
@@ -145,11 +145,11 @@ The MPI standard prescribes portable Fortran syntax for the
 *TARGET_DISP* argument only for Fortran 90. FORTRAN 77 users may use the
 non-portable syntax
 
-::
+.. code-block:: fortran
 
         INTEGER*MPI_ADDRESS_KIND TARGET_DISP
 
-where MPI_ADDRESS_KIND is a constant defined in mpif.h and gives the
+where ``MPI_ADDRESS_KIND`` is a constant defined in ``mpif.h`` and gives the
 length of the declared integer in bytes.
 
 
@@ -172,4 +172,6 @@ ERRORS
 .. include:: ./ERRORS.rst
 
 .. seealso::
-   :ref:`MPI_Put` :ref:`MPI_Get_accumulate` :ref:`MPI_Reduce`
+   * :ref:`MPI_Put`
+   * :ref:`MPI_Get_accumulate`
+   * :ref:`MPI_Reduce`

docs/man-openmpi/man3/MPI_Add_error_class.3.rst

@@ -6,9 +6,7 @@ MPI_Add_error_class
 
 .. include_body
 
-::
-
-   MPI_Add_error_class - Creates a new error class and returns its value
+:ref:`MPI_Add_error_class` - Creates a new error class and returns its value
 
 
 SYNTAX
@@ -50,7 +48,7 @@ Fortran 2008 Syntax
 OUTPUT PARAMETERS
 -----------------
 * ``errorclass``: New error class (integer).
-* ``IERROR``: Fortran only: Error status (integer).
+* ``ierror``: Fortran only: Error status (integer).
 
 DESCRIPTION
 -----------
@@ -83,4 +81,7 @@ ERRORS
 .. include:: ./ERRORS.rst
 
 .. seealso::
-   :ref:`MPI_Add_error_code` :ref:`MPI_Add_error_string` :ref:`MPI_Error_class` :ref:`MPI_Error_string`
+   * :ref:`MPI_Add_error_code`
+   * :ref:`MPI_Add_error_string`
+   * :ref:`MPI_Error_class`
+   * :ref:`MPI_Error_string`

docs/man-openmpi/man3/MPI_Add_error_code.3.rst

@@ -54,7 +54,7 @@ INPUT PARAMETER
 OUTPUT PARAMETERS
 -----------------
 * ``errorcode``: Error code returned by an MPI routine or an MPI error class (integer).
-* ``IERROR``: Fortran only: Error status (integer).
+* ``ierror``: Fortran only: Error status (integer).
 
 DESCRIPTION
 -----------
@@ -78,4 +78,5 @@ ERRORS
 .. include:: ./ERRORS.rst
 
 .. seealso::
-   :ref:`MPI_Add_error_class` :ref:`MPI_Error_class`
+   * :ref:`MPI_Add_error_class`
+   * :ref:`MPI_Error_class`

docs/man-openmpi/man3/MPI_Add_error_string.3.rst

@@ -6,9 +6,7 @@ MPI_Add_error_string
 
 .. include_body
 
-::
-
-   MPI_Add_error_string - Associates a string with an error code or class
+:ref:`MPI_Add_error_string` - Associates a string with an error code or class
 
 
 SYNTAX
@@ -56,7 +54,7 @@ INPUT PARAMETERS
 
 OUTPUT PARAMETER
 ----------------
-* ``IERROR``: Fortran only: Error status (integer).
+* ``ierror``: Fortran only: Error status (integer).
 
 DESCRIPTION
 -----------
@@ -75,4 +73,7 @@ ERRORS
 .. include:: ./ERRORS.rst
 
 .. seealso::
-   :ref:`MPI_Add_error_class` :ref:`MPI_Add_error_code` :ref:`MPI_Error_class` :ref:`MPI_Error_string`
+   * :ref:`MPI_Add_error_class`
+   * :ref:`MPI_Add_error_code`
+   * :ref:`MPI_Error_class`
+   * :ref:`MPI_Error_string`