Skip to content

Commit 5ddee4f

Browse files
jsquyresjsquyres
authored
Merge pull request #11242 from jsquyres/pr/docs-add-mesages-to-top-of-all-faq-pages
Docs updates
2 parents ba274c5 + 541bfc6 commit 5ddee4f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+538
-572
lines changed

‎docs/Makefile.am

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -35,22 +35,23 @@ IMAGE_SOURCE_FILES = \
3535
$(srcdir)/installing-open-mpi/required-support-libraries-dependency-graph.png
3636
RST_SOURCE_FILES = \
3737
$(srcdir)/*.rst \
38-
$(srcdir)/app-debug/*.rst \
39-
$(srcdir)/building-apps/*.rst \
40-
$(srcdir)/developers/*.rst \
41-
$(srcdir)/faq/*.rst \
42-
$(srcdir)/features/*.rst \
38+
$(srcdir)/release-notes/*.rst \
4339
$(srcdir)/installing-open-mpi/*.rst \
4440
$(srcdir)/installing-open-mpi/*/*.rst \
41+
$(srcdir)/features/*.rst \
42+
$(srcdir)/building-apps/*.rst \
43+
$(srcdir)/launching-apps/*.rst \
44+
$(srcdir)/tuning-apps/*.rst \
45+
$(srcdir)/tuning-apps/*/*.rst \
46+
$(srcdir)/app-debug/*.rst \
47+
$(srcdir)/faq/*.rst \
48+
$(srcdir)/developers/*.rst \
4549
$(srcdir)/license/*.rst \
50+
$(srcdir)/news/*.rst \
4651
$(srcdir)/man-openmpi/*.rst \
4752
$(srcdir)/man-openmpi/man*/*.rst \
4853
$(srcdir)/man-openshmem/*.rst \
49-
$(srcdir)/man-openshmem/man*/*.rst \
50-
$(srcdir)/networking/*.rst \
51-
$(srcdir)/news/*.rst \
52-
$(srcdir)/release-notes/*.rst \
53-
$(srcdir)/running-apps/*.rst
54+
$(srcdir)/man-openshmem/man*/*.rst
5455

5556
EXTRA_DIST = \
5657
requirements.txt \

‎docs/contributing.rst

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -105,9 +105,18 @@ process as described in Section 11 of the Linux kernel document on
105105
<https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`_.
106106
Each proposed contribution to the Open MPI code base must include the
107107
text ``Signed-off-by:`` followed by the contributor's name and email
108-
address. This is a developer's certification that he or she has the
109-
right to submit the patch for inclusion into the project, and
110-
indicates agreement to the Developer's Certificate of Origin:
108+
address.
109+
110+
.. admonition:: Pro tip
111+
:class: tip
112+
113+
You can use the ``-s`` flag to the ``git commit`` command (i.e.,
114+
``git commit -s ...``) to automatically add the appropriate
115+
``Signed-off-by:`` line to your commit message.
116+
117+
The ``Signed-off-by:`` line is a developer's certification that he or
118+
she has the right to submit the patch for inclusion into the project,
119+
and indicates agreement to the Developer's Certificate of Origin:
111120

112121
By making a contribution to this project, I certify that:
113122

@@ -145,12 +154,18 @@ inadvertently made without the required certification.
145154
If you have not already done so, please ensure that *every* commit in
146155
your pull request contains the ``Signed-off-by:`` line.
147156

157+
Git commit messages
158+
^^^^^^^^^^^^^^^^^^^
159+
160+
Please write a good Git commit message, with a short first line
161+
describing *what* was done, and then a description of *why* it was
162+
done.
163+
148164
.. admonition:: Pro tip
149165
:class: tip
150166

151-
You can use the ``-s`` flag to the ``git commit`` command (i.e.,
152-
``git commit -s ...``) to automatically add the appropriate
153-
``Signed-off-by:`` line to your commit message.
167+
`See this blog entry <https://cbea.ms/git-commit/>`_ for an
168+
excellent description of how to write a good Git commit message.
154169

155170
Code style
156171
^^^^^^^^^^

‎docs/developers/terminology.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ terminology in order to make the rest of the discussion easier.
88
Modular Component Architecture (MCA)
99
------------------------------------
1010

11-
:doc:`See this section </running-apps/tuning>` for a discussion of the
12-
Modular Component Architecture (MCA). Seriously. Go read it now.
13-
From reading that section, you should understand the following terms
14-
before continuing reading these docs:
11+
:ref:`See this section <label-mca>` for a discussion of the Modular
12+
Component Architecture (MCA). Seriously. Go read it now. From
13+
reading that section, you should understand the following terms before
14+
continuing reading these docs:
1515

1616
* Project
1717
* Framework

‎docs/faq/building-open-mpi.rst

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,18 @@
11
Building Open MPI
22
=================
33

4-
.. TODO How can I create a TOC just for this page here at the top?
4+
.. error:: This section represents old content from the <= v4.x FAQ
5+
that has not been properly converted to the new-style
6+
documentation. The content here was perfunctorily
7+
converted to RST, but it still needs to be:
8+
9+
#. Converted from a question-and-answer style to a regular
10+
documentation style (like the rest of these docs).
11+
#. Removed from this section and folded into other sections
12+
in these docs.
13+
14+
To be clear, this section will eventually be deleted; do
15+
not write any new content in this section.
516

617
/////////////////////////////////////////////////////////////////////////
718

‎docs/faq/fault-tolerance.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,21 @@
11
Fault Tolerance
22
===============
33

4+
.. error:: This section represents old content from the <= v4.x FAQ
5+
that has not been properly converted to the new-style
6+
documentation. The content here was perfunctorily
7+
converted to RST, but it still needs to be:
8+
9+
#. Converted from a question-and-answer style to a regular
10+
documentation style (like the rest of these docs).
11+
#. Removed from this section and folded into other sections
12+
in these docs.
13+
14+
To be clear, this section will eventually be deleted; do
15+
not write any new content in this section.
16+
17+
/////////////////////////////////////////////////////////////////////////
18+
419
What is "fault tolerance"?
520
--------------------------
621

‎docs/faq/general-tuning.rst

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,18 @@
11
General Tuning
22
==============
33

4-
.. TODO How can I create a TOC just for this page here at the top?
4+
.. error:: This section represents old content from the <= v4.x FAQ
5+
that has not been properly converted to the new-style
6+
documentation. The content here was perfunctorily
7+
converted to RST, but it still needs to be:
8+
9+
#. Converted from a question-and-answer style to a regular
10+
documentation style (like the rest of these docs).
11+
#. Removed from this section and folded into other sections
12+
in these docs.
13+
14+
To be clear, this section will eventually be deleted; do
15+
not write any new content in this section.
516

617
/////////////////////////////////////////////////////////////////////////
718

@@ -162,10 +173,9 @@ the ``mpi_warn_on_fork`` MCA parameter. For example:
162173
shell$ mpirun --mca mpi_warn_on_fork 0 ...
163174
164175
Of course, systems that ``dlopen("libmpi.so", ...)`` may not use Open
165-
MPI's ``mpirun``, and therefore may need to use (JMS: this ref no
166-
longer exists -- it moved to running-apps/tuning.rst) a different
167-
mechanism to set MCA parameters
168-
<faq-general-tuning-setting-mca-params>`.
176+
MPI's ``mpirun``, and therefore may need to use (**JMS: this ref no
177+
longer exists -- it moved to elsewhere**) a different mechanism to set
178+
MCA parameters <faq-general-tuning-setting-mca-params>`.
169179

170180
/////////////////////////////////////////////////////////////////////////
171181

‎docs/faq/index.rst

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
1-
.. Open MPI FAQ
1+
Frequently Asked Questions (FAQ)
2+
================================
23

3-
This page will likely eventually go away (i.e., the "FAQ" section
4-
will likely disappear -- its contents will likely just be folded in
5-
elsewhere in the document).
4+
.. error:: This section represents old content from the <= v4.x FAQ
5+
that has not been properly converted to the new-style
6+
documentation. The content here was perfunctorily
7+
converted to RST, but it still needs to be:
68

9+
#. Converted from a question-and-answer style to a regular
10+
documentation style (like the rest of these docs).
11+
#. Removed from this section and folded into other sections
12+
in these docs.
713

8-
Frequently Asked Questions (FAQ)
9-
================================
14+
To be clear, this section will eventually be deleted; do
15+
not write any new content in this section.
1016

1117
The pages below include questions that we are asked frequently enough
1218
that they are worth categorizing in an official way.
@@ -23,7 +29,4 @@ that they are worth categorizing in an official way.
2329

2430
large-clusters
2531

26-
ompio
27-
macos
28-
2932
general-tuning

‎docs/faq/large-clusters.rst

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,18 @@
11
Large Clusters
22
==============
33

4-
.. TODO How can I create a TOC just for this page here at the top?
4+
.. error:: This section represents old content from the <= v4.x FAQ
5+
that has not been properly converted to the new-style
6+
documentation. The content here was perfunctorily
7+
converted to RST, but it still needs to be:
8+
9+
#. Converted from a question-and-answer style to a regular
10+
documentation style (like the rest of these docs).
11+
#. Removed from this section and folded into other sections
12+
in these docs.
13+
14+
To be clear, this section will eventually be deleted; do
15+
not write any new content in this section.
516

617
/////////////////////////////////////////////////////////////////////////
718

‎docs/faq/macos.rst

Lines changed: 0 additions & 104 deletions
This file was deleted.

0 commit comments

Comments
 (0)