docs: fix HTML word wapping in table cells

The sphinx_rtd_theme does not properly handle wrapping long lines in table cells when rendering to HTML due to a CSS issue (see readthedocs/sphinx_rtd_theme#1505). Until the issue is fixed upstream in sphinx_rtd_theme, we can simply override the CSS here. This commit overrides the CSS in conf.py and also touches up some places where we previously tried to work around the lack of word wrapping. Signed-off-by: Jeff Squyres <jeff@squyres.com>
bosilca · Feb 14, 2024 · 815da65 · 815da65
1 parent 60e6df4
commit 815da65
Show file tree

Hide file tree

Showing 4 changed files with 69 additions and 52 deletions.
diff --git a/docs/building-apps/deprecation-warnings.rst b/docs/building-apps/deprecation-warnings.rst
@@ -93,7 +93,7 @@ listed :ref:`here <label-removed-mpi-constructs>`.
       - MPI-4.0 (2021)
 
     * - :ref:`MPI_SIZEOF <label-mpi-sizeof>`
-      -  Fortran intrinsics``c_sizeof`` or ``storage_size``
+      - Fortran intrinsics``c_sizeof`` or ``storage_size``
       - MPI-4.0 (2021)
 
 .. _label-mpi-keyval-create:

diff --git a/docs/conf.py b/docs/conf.py
@@ -225,3 +225,16 @@ def _doit(topdir):
 .. |deprecated_favor| replace:: this routine is deprecated in favor of
 
 """
+
+# The sphinx_rtd_theme does not properly handle wrapping long lines in
+# table cells when rendering to HTML due to a CSS issue (see
+# https://github.com/readthedocs/sphinx_rtd_theme/issues/1505).  Until
+# the issue is fixed upstream in sphinx_rtd_theme, we can simply
+# override the CSS here.
+rst_prolog += """
+.. raw:: html
+
+   <style>
+   .wy-table-responsive table td,.wy-table-responsive table th{white-space:normal}
+   </style>
+"""
diff --git a/docs/installing-open-mpi/required-support-libraries.rst b/docs/installing-open-mpi/required-support-libraries.rst
@@ -7,37 +7,38 @@ Open MPI requires the following support libraries with the minimum listed versio
 
 .. list-table::
    :header-rows: 1
-   :widths: 10 10 25
 
    * - Library
      - Minimum version
      - Notes
    * - `Hardware Locality <https://www.open-mpi.org/projects/hwloc/>`_
      - |hwloc_min_version|
-     - | This library is required; Open MPI will not build without it.
+     - This library is required; Open MPI will not build without it.
    * - `Libevent <https://libevent.org/>`_
      - |event_min_version|
-     - | This library is required; Open MPI will not build without it.
+     - This library is required; Open MPI will not build without it.
    * - `PMIx <https://pmix.org/>`_
      - |pmix_min_version|
-     - | This library is required; Open MPI will not build without it.
+     - This library is required; Open MPI will not build without it.
    * - `PRRTE <https://github.com/openpmix/prrte>`_
      - |prte_min_version|
-     - | This library is optional in some environments. PRRTE provides
-       | Open MPI's full-featured ``mpirun`` / ``mpiexec`` MPI
-       | application launchers (the two are identical; they are symbolic
-       | links to the same executable).
-
-       * | If your environment uses another MPI application launcher
-         | (e.g., Slurm users can use the ``srun`` launcher to "direct
-         | launch" Open MPI applications), then the use of PRRTE is
-         | optional.
-       * | If your environment has no other MPI application launcher, then
-         | you need to install PRRTE and build Open MPI with PRRTE
-         | support.
-       * | Open MPI can use the copy of PRRTE embedded in its source code
-         | tree, or compile/link against an external PRRTE installation.
-         | :ref:`See this section for details about how to specify each method <label-building-ompi-cli-options-required-support-libraries>`.
+     - This library is optional in some environments. PRRTE provides
+       Open MPI's full-featured ``mpirun`` / ``mpiexec`` MPI
+       application launchers (the two are identical; they are symbolic
+       links to the same executable).
+
+       * If your environment uses another MPI application launcher
+         (e.g., Slurm users can use the ``srun`` launcher to "direct
+         launch" Open MPI applications), then the use of PRRTE is
+         optional.
+       * If your environment has no other MPI application launcher, then
+         you need to install PRRTE and build Open MPI with PRRTE
+         support.
+       * Open MPI can use the copy of PRRTE embedded in its source
+         code tree, or compile/link against an external PRRTE
+         installation.  :ref:`See this section for details about how
+         to specify each method
+         <label-building-ompi-cli-options-required-support-libraries>`.
 
 Since these support libraries are fundamental to Open MPI's operation
 and not universally available in all environments, they are directly

diff --git a/docs/launching-apps/ssh.rst b/docs/launching-apps/ssh.rst
@@ -203,35 +203,38 @@ shells are picky about the permissions of the startup file, for
 example).  The list below contains some common shells and the startup
 files that they read/execute upon login:
 
-.. error:: TODO This rendering sucks, but I couldn't make it play nice
-           with list-table, either.  :-(
-
-* ``bash`` or ``zsh``:
-
-  * **Non-interactive login:** ``$HOME/.bashrc`` if it exists.
-  * **Interactive login**: ``$HOME/.bash_profile`` if it exists, or
-    ``$HOME/.bash_login`` if it exists, or ``$HOME/.profile`` if it
-    exists (in that order). Note that some Linux distributions
-    automatically come with ``$HOME/.bash_profile`` scripts for users
-    that automatically execute ``$HOME/.bashrc`` as well. Consult the
-    bash man page for more information.
-
-* ``sh``:
-
-  * **Non-interactive login:** This shell does not execute any file
-    automatically, so Open MPI will execute the ``$HOME/.profile``
-    script before invoking Open MPI executables on remote nodes
-  * **Interactive login:** ``$HOME/.profile``
-
-* ``csh``:
-
-  * **Non-interactive login:** ``$HOME/.cshrc``
-  * **Interactive login:** ``$HOME/.cshrc`` followed by
-    ``$HOME/.login``
-
-* ``tcsh``:
-
-  * **Non-interactive login:** ``$HOME/.tcshrc`` if it exists,
-    ``$HOME/.cshrc`` if it does not
-  * **Interactive login:** ``$HOME/.tcshrc`` if it exists,
-    ``$HOME/.cshrc`` if it does not, followed by ``$HOME/.login``
+.. list-table::
+   :header-rows: 1
+
+   * - Shell
+     - Non-interactive login
+     - Interactive login
+
+   * - ``bash`` or ``zsh``
+     - ``$HOME/.bashrc`` if it exists.
+     - #. ``$HOME/.bash_profile`` if it exists, or
+       #. ``$HOME/.bash_login`` if it exists, or
+       #. ``$HOME/.profile`` if it exists (in that order).
+
+       Note that some Linux distributions automatically come
+       with ``$HOME/.bash_profile`` scripts for users that
+       automatically execute ``$HOME/.bashrc`` as well. Consult the
+       bash man page for more information.
+
+   * - ``sh``
+     - This shell does not execute any file automatically, so Open MPI
+       will execute the ``$HOME/.profile`` script before invoking Open
+       MPI executables on remote nodes
+     - ``$HOME/.profile``
+
+   * - ``csh``
+     - ``$HOME/.cshrc``
+     - ``$HOME/.cshrc`` followed by ``$HOME/.login``
+
+   * - ``tcsh``
+     - #. ``$HOME/.tcshrc`` if it exists, or
+       #. ``$HOME/.cshrc`` if it does not
+     - #. ``$HOME/.tcshrc`` if it exists, or
+       #. ``$HOME/.cshrc`` if it does not
+
+       Afterwards, execute ``$HOME/.login``