Skip to content

Commit 1b5dc73

Browse files
jsquyresjsquyres
authored
Merge pull request #10114 from jsquyres/pr/trivial-docs-updates
Continued docs updates
2 parents 758c759 + 0548757 commit 1b5dc73

20 files changed

+213
-113
lines changed

‎.readthedocs.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,4 @@ version: 2
88
# Build documentation in the docs/ directory with Sphinx
99
sphinx:
1010
configuration: docs/conf.py
11+
fail_on_warning: true

‎docs/Makefile.am

Lines changed: 41 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -785,6 +785,40 @@ OSHMEM_MAN1_BUILT = $(OSHMEM_MAN1:%.1=$(MAN_OUTDIR)/%.1)
785785
OSHMEM_MAN3_RST = $(OSHMEM_MAN3:%.3=man-oshmem/man3/%.3.rst)
786786
OSHMEM_MAN3_BUILT = $(OSHMEM_MAN3:%.3=$(MAN_OUTDIR)/%.3)
787787

788+
EXTRA_DIST += \
789+
$(OMPI_MAN1_BUILT) \
790+
$(OMPI_MAN3_BUILT) \
791+
$(OMPI_MAN5_BUILT) \
792+
$(OSHMEM_MAN1_BUILT) \
793+
$(OSHMEM_MAN3_BUILT)
794+
795+
###########################################################################
796+
797+
# These files are not generated by Sphinx (they are redirects to
798+
# Sphinx-generated man pages).
799+
OMPI_MAN1_REDIRECTS = \
800+
man-openmpi/man1/mpicc.1 \
801+
man-openmpi/man1/mpicxx.1 \
802+
man-openmpi/man1/mpic++.1 \
803+
man-openmpi/man1/mpifort.1 \
804+
man-openmpi/man1/mpif77.1 \
805+
man-openmpi/man1/mpif90.1 \
806+
man-openmpi/man1/mpijavac.1
807+
808+
OSHMEM_MAN1_REDIRECTS = \
809+
man-openshmem/man1/oshcc.1 \
810+
man-openshmem/man1/oshcxx.1 \
811+
man-openshmem/man1/oshc++.1 \
812+
man-openshmem/man1/oshfort.1 \
813+
man-openshmem/man1/shmemcc.1 \
814+
man-openshmem/man1/shmemcxx.1 \
815+
man-openshmem/man1/shmemc++.1 \
816+
man-openshmem/man1/shmemfort.1
817+
818+
EXTRA_DIST += \
819+
$(OMPI_MAN1_REDIRECTS) \
820+
$(OSHMEM_MAN1_REDIRECTS)
821+
788822
###########################################################################
789823
if OPAL_BUILD_DOCS
790824

@@ -840,32 +874,19 @@ endif OPAL_BUILD_DOCS
840874
###########################################################################
841875
if OPAL_INSTALL_DOCS
842876

843-
dist_man1_MANS = \
877+
man1_MANS = \
844878
$(OMPI_MAN1_BUILT) \
845-
man-openmpi/man1/mpicc.1 \
846-
man-openmpi/man1/mpicxx.1 \
847-
man-openmpi/man1/mpic++.1 \
848-
man-openmpi/man1/mpifort.1 \
849-
man-openmpi/man1/mpif77.1 \
850-
man-openmpi/man1/mpif90.1 \
851-
man-openmpi/man1/mpijavac.1
879+
$(OMPI_MAN1_REDIRECTS)
852880

853-
dist_man3_MANS = $(OMPI_MAN3_BUILT)
854-
dist_man5_MANS = $(OMPI_MAN5_BUILT)
881+
man3_MANS = $(OMPI_MAN3_BUILT)
882+
man5_MANS = $(OMPI_MAN5_BUILT)
855883

856884
if PROJECT_OSHMEM
857-
dist_man1_MANS += \
885+
man1_MANS += \
858886
$(OSHMEM_MAN1_BUILT) \
859-
man-openshmem/man1/oshcc.1 \
860-
man-openshmem/man1/oshcxx.1 \
861-
man-openshmem/man1/oshc++.1 \
862-
man-openshmem/man1/oshfort.1 \
863-
man-openshmem/man1/shmemcc.1 \
864-
man-openshmem/man1/shmemcxx.1 \
865-
man-openshmem/man1/shmemc++.1 \
866-
man-openshmem/man1/shmemfort.1
887+
$(OSHMEM_MAN1_REDIRECTS)
867888

868-
dist_man3_MANS += $(OSHMEM_MAN3_BUILT)
889+
man3_MANS += $(OSHMEM_MAN3_BUILT)
869890
endif
870891

871892
endif OPAL_INSTALL_DOCS

‎docs/conf.py

Lines changed: 60 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,8 @@
3131
ompi_data = dict()
3232
for ompi_line in ompi_lines:
3333
if '#' in ompi_line:
34-
ompi_line, _ = ompi_line.split("#")
34+
parts = ompi_line.split("#")
35+
ompi_line = parts[0]
3536
ompi_line = ompi_line.strip()
3637

3738
if '=' not in ompi_line:
@@ -40,11 +41,63 @@
4041
ompi_key, ompi_val = ompi_line.split("=")
4142
ompi_data[ompi_key.strip()] = ompi_val.strip()
4243

43-
# "release" is a sphinx config variable -- assign it to the computed
44-
# Open MPI version number.
45-
series = f"{ompi_data['major']}.{ompi_data['minor']}.x"
46-
release = f"{ompi_data['major']}.{ompi_data['minor']}.{ompi_data['release']}{ompi_data['greek']}"
44+
ompi_series = f"v{ompi_data['major']}.{ompi_data['minor']}.x"
45+
ompi_ver = f"v{ompi_data['major']}.{ompi_data['minor']}.{ompi_data['release']}{ompi_data['greek']}"
4746

47+
# "release" is a sphinx config variable: assign it to the computed
48+
# Open MPI version number. The ompi_ver string begins with a "v"; the
49+
# Sphinx release variable should not include this prefix "v".
50+
release = ompi_ver[1:]
51+
52+
# If we are building in a ReadTheDocs.io environment, there will be a
53+
# READTHEDOCS environment variables that tell us what version to use.
54+
# Relevant RTD env variables (documented
55+
# https://docs.readthedocs.io/en/stable/builds.html#build-environment):
56+
#
57+
# - READTHEDOCS: will be "True"
58+
# - READTHEDOCS_VERSION: The RTD slug of the version which is being
59+
# built (e.g., "latest")
60+
# - READTHEDOCS_VERSION_NAME: Corresponding version name as displayed
61+
# in RTD's version switch menu (e.g., "stable")
62+
# - READTHEDOCS_VERSION_TYPE: Type of the event triggering the build
63+
# (e.g., "branch", "tag", "external" (for PRs), or "unknown").
64+
#
65+
# If we're building in an RTD environment for a tag or external (i.e.,
66+
# PR), use the RTD version -- not what we just read from the VERSIONS
67+
# file.
68+
import os
69+
key = 'READTHEDOCS'
70+
if key in os.environ and os.environ[key] == 'True':
71+
print("OMPI: found ReadTheDocs build environment")
72+
73+
rtd_v = os.environ['READTHEDOCS_VERSION']
74+
if os.environ['READTHEDOCS_VERSION_TYPE'] == 'external':
75+
# Make "release" be shorter than the full "ompi_ver" value.
76+
release = f'PR #{rtd_v}'
77+
ompi_ver += f' (Github PR #{rtd_v})'
78+
else:
79+
ompi_ver = rtd_v
80+
81+
# The "release" Sphinx variable is supposed to be expressed as
82+
# a simple value, such as "A.B.C[rcX]" (without a leading
83+
# "v"). The ompi_ver value will be one of two things:
84+
#
85+
# - a git branch name (of the form "vA.B.x")
86+
# - a git tag (of the form "A.B.C[rcX]")
87+
#
88+
# If there's a leading "v", we need to strip it.
89+
release = ompi_ver
90+
if ompi_ver[0] == 'v':
91+
release = ompi_ver[1:]
92+
93+
# Override the branch names "master" and "main" (that would have
94+
# come from the ReadTheDocs version slug) to be "head of
95+
# development".
96+
if release == 'main' or release == 'master':
97+
ompi_ver = 'head of development'
98+
99+
print(f"OMPI: release = {release}")
100+
print(f"OMPI: ompi_ver = {ompi_ver}")
48101

49102
# -- General configuration ---------------------------------------------------
50103

@@ -124,6 +177,6 @@ def _doit(topdir):
124177
.. |rarrow| unicode:: U+02192 .. Right arrow
125178
126179
.. |year| replace:: {year}
127-
.. |ompi_ver| replace:: v{release}
128-
.. |ompi_series| replace:: v{series}
180+
.. |ompi_ver| replace:: {ompi_ver}
181+
.. |ompi_series| replace:: {ompi_series}
129182
"""

‎docs/faq/debugging.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -538,7 +538,7 @@ There are two cases:
538538
<https://valgrind.org/docs/valgrind2007.pdf>`_.
539539
For an evaluation of various internal implementation alternatives of Shadow Memory, please see
540540
`Building Workload Characterization Tools with Valgrind
541-
<https://www.valgrind.org/njn/pubs/shadow-memory2007-talk.ppt>`_.
541+
<https://valgrind.org/docs/iiswc2006.pdf>`_.
542542

543543

544544
Further information and performance data with the NAS Parallel

‎docs/faq/fault-tolerance.rst

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,14 @@
11
Fault Tolerance
22
===============
33

4-
.. TODO Hello world
5-
6-
/////////////////////////////////////////////////////////////////////////
7-
84
What is "fault tolerance"?
95
--------------------------
106

117
The phrase "fault tolerance" means many things to many
12-
people. Typical definitions range from user processes dumping vital
13-
state to disk periodically to checkpoint/restart of running processes
14-
to elaborate recreate-process-state-from-incremental-pieces schemes to
15-
... (you get the idea).
8+
people. Typical definitions include user processes dumping vital
9+
state to disk periodically, checkpoint/restart of running processes,
10+
elaborate recreate-process-state-from-incremental-pieces schemes,
11+
and many others.
1612

1713
In the scope of Open MPI, we typically define "fault tolerance" to
1814
mean the ability to recover from one or more component failures in a
@@ -99,7 +95,7 @@ links below:
9995
* `MPI Forum's Fault Tolerance Working Group <https://github.com/mpiwg-ft/ft-issues/wiki>`_
10096
* Fault Tolerant MPI Prototype:
10197
* `Development / code <https://bitbucket.org/icldistcomp/ulfm2>`_
102-
* `Information and support <http://fault-tolerance.org/>`_
98+
* `Information and support <https://fault-tolerance.org/>`_
10399

104100
Support for other types of resilience (e.g., :ref:`data reliability <faq-ft-data-reliability-label>`,
105101
checkpoint) has been deprecated over the years

‎docs/faq/running-mpi-apps.rst

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -762,9 +762,12 @@ Several notable options are:
762762
How do I use the ``--hostfile`` option to ``mpirun``?
763763
-----------------------------------------------------
764764
765-
.. error:: TODO For cross reference, this is the PRRTE man page section
766-
about ``--hostfile``:
767-
https://github.com/openpmix/prrte/blame/master/src/tools/prte/prte-map.1.md#L236
765+
.. error:: TODO For cross reference, this is the PRRTE man page
766+
section about ``--hostfile``:
767+
https://github.com/openpmix/prrte/blob/b70a6f1a8d424e396c40c999a656b04e76cc0f91/src/tools/prte/prte-map.1.md?plain=1#L236
768+
A subsequent commit removed this markdown file; the commit
769+
message refers to moving the markdown file to another git
770+
repo, but I didn't chase down where it went.
768771
769772
The ``--hostfile`` option to ``mpirun`` takes a filename that lists
770773
hosts on which to launch MPI processes.

‎docs/faq/sysadmin.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ to tweak are:
220220
parameters in *levels*, as defined by the MPI_T interface from
221221
the MPI standard. You will need to specify ``--level 9`` (or
222222
``--all``) to show *all* MCA parameters. `See this blog entry
223-
<http://blogs.cisco.com/performance/open-mpi-and-the-mpi-3-mpi_t-interface>`_
223+
<https://blogs.cisco.com/performance/open-mpi-and-the-mpi-3-mpi_t-interface>`_
224224
for further information.
225225

226226
.. code-block:: sh

‎docs/features/ulfm.rst

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ execution environment up and running.
2323
This implementation produces the three supplementary error codes and
2424
five supplementary interfaces defined in the communicator section of
2525
the `ULFM chapter
26-
<http://fault-tolerance.org/wp-content/uploads/2012/10/20170221-ft.pdf>`_
26+
<https://fault-tolerance.org/wp-content/uploads/2012/10/20170221-ft.pdf>`_
2727
standard draft document.
2828

2929
* ``MPIX_ERR_PROC_FAILED`` when a process failure prevents the
@@ -95,7 +95,7 @@ please use:
9595
J. Dongarra: Post-failure recovery of MPI communication
9696
capability: Design and rationale. IJHPCA 27(3): 244-254 (2013).*
9797

98-
Available from: http://journals.sagepub.com/doi/10.1177/1094342013488238.
98+
Available from: https://journals.sagepub.com/doi/10.1177/1094342013488238.
9999

100100
Building ULFM support in Open MPI
101101
---------------------------------
@@ -522,9 +522,8 @@ [email protected]!). Visit these pages to subscribe to the
522522
lists: https://groups.google.com/forum/#!forum/ulfm
523523

524524
When submitting questions and problems, be sure to include as much
525-
extra information as possible. This web page details all the
526-
information that we request in order to provide assistance:
527-
http://www.open-mpi.org/community/help/
525+
extra information as possible. See the :doc:`Getting help
526+
</getting-help>` section for more details.
528527

529528
Thanks for your time.
530529

‎docs/index.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. image:: openmpi_logo.png
22
:align: right
33

4-
Open MPI
5-
========
4+
Open MPI |ompi_ver|
5+
===================
66

77
`The Open MPI Project <https://www.open-mpi.org/>`_ is an open source
88
implementation of the `Message Passing Interface (MPI) specification
@@ -14,11 +14,10 @@ order to build the best MPI library available. Open MPI offers
1414
advantages for system and software vendors, application developers and
1515
computer science researchers.
1616

17-
Other documentation
18-
===================
17+
Documentation locations
18+
=======================
1919

20-
Documentation for other versions of Open can be found in the following
21-
locations:
20+
Documentation for Open can be found in the following locations:
2221

2322
.. list-table::
2423
:header-rows: 1
@@ -28,7 +27,8 @@ locations:
2827

2928
* - v5.0.0 and later
3029
- Open MPI documentation has consolidated and moved to
31-
ReadTheDocs.io.
30+
31+
https://docs.open-mpi.org/.
3232

3333
This particular documentation is for |ompi_ver|; use the
3434
selector in the

0 commit comments

Comments
 (0)