Beautification of rst documentation

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`

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

@@ -42,7 +42,7 @@ INPUT PARAMETER
 OUTPUT PARAMETERS
 -----------------
 * ``address``: Address of location (integer).
-* ``IERROR``: Fortran only: Error status (integer).
+* ``ierror``: Fortran only: Error status (integer).
 
 DESCRIPTION
 -----------
@@ -55,25 +55,24 @@ function. Returns the (byte) address of location.
 
 Example: Using :ref:`MPI_Address` for an array.
 
-::
+.. code-block:: fortran
 
    REAL A(100,100)
 
-|
-| INTEGER I1, I2, DIFF
-| CALL MPI_ADDRESS(A(1,1), I1, IERROR)
-| CALL MPI_ADDRESS(A(10,10), I2, IERROR)
-| DIFF = I2 - I1
-| ! The value of DIFF is 909*sizeofreal; the values of I1 and I2 are
-| ! implementation dependent.
+   INTEGER I1, I2, DIFF
+   CALL MPI_ADDRESS(A(1,1), I1, IERROR)
+   CALL MPI_ADDRESS(A(10,10), I2, IERROR)
+   DIFF = I2 - I1
+   ! The value of DIFF is 909*sizeof(real)
+   !the values of I1 and I2 are implementation dependent.
 
 
 NOTES
 -----
 
 This routine is provided for both Fortran and C programmers and may be
 useful when writing portable code. In the current release, the address
-returned by this routine will be the same as that produced by the C &
+returned by this routine will be the same as that produced by the C ``&``
 operator.
 
 C users may be tempted to avoid using :ref:`MPI_Address` and rely on the
@@ -92,4 +91,4 @@ ERRORS
 .. include:: ./ERRORS.rst
 
 .. seealso::
-   :ref:`MPI_Get_address`
+   * :ref:`MPI_Get_address`

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

@@ -73,11 +73,11 @@ in the same object referenced by *base*, as described in MPI-3.1 section
 correct MPI_Aint representation of the output address, as if the process
 that originally produced *base* had called:
 
-::
+.. code-block:: c
 
-           MPI_Get_address ((char *) base + disp, &result);
+   MPI_Get_address ((char *) base + disp, &result);
 
-**MPI_Aint_diff** produces a new MPI_Aint value that is equivalent to
+:ref:`MPI_Aint_diff` produces a new MPI_Aint value that is equivalent to
 the difference between *addr1* and *addr2* arguments, where *addr1*
 and *addr2* represent addresses returned by calls to
 :ref:`MPI_Get_address`.  The resulting address is valid only at the
@@ -86,9 +86,9 @@ must correspond to locations in the same object in the same process,
 as described in MPI-3.1 section 4.1.12. The difference is calculated
 in a manner that results in the signed difference from *addr1* to
 *addr2*, as if the process that originally produced the addresses had
-called (char \*) *addr1* - (char \*) *addr2* on the addresses
+called ``(char *) addr1`` - ``(char *) addr2`` on the addresses
 initially passed to :ref:`MPI_Get_address`.
 
 
 .. seealso::
-   :ref:`MPI_Get_address`
+   * :ref:`MPI_Get_address`

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

@@ -112,7 +112,7 @@ OUTPUT PARAMETERS
 -----------------
 * ``recvbuf``: Address of receive buffer (choice).
 * ``request``: Request (handle, non-blocking only).
-* ``IERROR``: Fortran only: Error status (integer).
+* ``ierror``: Fortran only: Error status (integer).
 
 DESCRIPTION
 -----------
@@ -126,24 +126,26 @@ The type signature associated with sendcount, sendtype at a process must
 be equal to the type signature associated with recvcount, recvtype at
 any other process.
 
-The outcome of a call to MPI_Allgather(...) is as if all processes
+The outcome of a call to :ref:`MPI_Allgather` is as if all processes
 executed n calls to
 
-::
+.. code-block:: c
+
+     MPI_Gather(sendbuf, sendcount, sendtype, recvbuf, recvcount,
+                recvtype, root, comm);
 
-     MPI_Gather(sendbuf,sendcount,sendtype,recvbuf,recvcount,
-                recvtype,root,comm),
+     // for root = 0 , ..., n-1.
 
-for root = 0 , ..., n-1. The rules for correct usage of :ref:`MPI_Allgather`
+The rules for correct usage of :ref:`MPI_Allgather`
 are easily found from the corresponding rules for :ref:`MPI_Gather`.
 
 **Example:** The all-gather version of Example 1 in :ref:`MPI_Gather`. Using
 :ref:`MPI_Allgather`, we will gather 100 ints from every process in the group
 to every process.
 
-::
+.. code-block:: c
 
-   MPI_Comm comm;
+       MPI_Comm comm;
        int gsize,sendarray[100];
        int *rbuf;
        ...
@@ -167,12 +169,12 @@ receive its own contribution to the receive buffer. Specifically, the
 outcome of a call to :ref:`MPI_Allgather` that used the in-place option is
 identical to the case in which all processes executed *n* calls to
 
-::
+.. code-block:: c
 
-      MPI_ALLGATHER ( MPI_IN_PLACE, 0, MPI_DATATYPE_NULL, recvbuf,
-      recvcount, recvtype, root, comm )
+      MPI_Allgather( MPI_IN_PLACE, 0, MPI_DATATYPE_NULL, recvbuf,
+                     recvcount, recvtype, root, comm )
 
-   for root =0, ... , n-1.
+      // for root =0, ... , n-1.
 
 Note that MPI_IN_PLACE is a special kind of value; it has the same
 restrictions on its use as MPI_BOTTOM.
@@ -202,4 +204,5 @@ ERRORS
 .. include:: ./ERRORS.rst
 
 .. seealso::
-   :ref:`MPI_Allgatherv` :ref:`MPI_Gather`
+   * :ref:`MPI_Allgatherv`
+   * :ref:`MPI_Gather`