From 0d7b71d7de11cd02dda2d25aa65ce19e895a73cd Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Mon, 21 Aug 2023 09:32:59 -0400 Subject: [PATCH] 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 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. 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 --- docs/building-apps/deprecation-warnings.rst | 2 +- docs/conf.py | 13 ++++ .../required-support-libraries.rst | 36 +++++----- docs/launching-apps/ssh.rst | 67 ++++++++++--------- 4 files changed, 67 insertions(+), 51 deletions(-) diff --git a/docs/building-apps/deprecation-warnings.rst b/docs/building-apps/deprecation-warnings.rst index a7f3f46de9a..dabf456978d 100644 --- a/docs/building-apps/deprecation-warnings.rst +++ b/docs/building-apps/deprecation-warnings.rst @@ -93,7 +93,7 @@ listed :ref:`here `. - MPI-4.0 (2021) * - :ref:`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 index fc7034fa40a..bf192f5356b 100644 --- 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 + + +""" diff --git a/docs/installing-open-mpi/required-support-libraries.rst b/docs/installing-open-mpi/required-support-libraries.rst index 049c030d208..d6fc97b74a8 100644 --- a/docs/installing-open-mpi/required-support-libraries.rst +++ b/docs/installing-open-mpi/required-support-libraries.rst @@ -14,30 +14,30 @@ Open MPI requires the following support libraries with the minimum listed versio - Notes * - `Hardware Locality `_ - |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 `_ - |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 `_ - |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 `_ - |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 `. + - 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 `. 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 index 6a800c30eb3..969e55fa826 100644 --- 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``