docs: add warning to FAQ pages

jsquyres · jsquyres · commit c74dfde388ce · 2022-12-23T15:19:44.000-05:00
Put a big red box at the top of each of the FAQ pages so that no one
adds / edits the existing FAQ content (the goal is to fold all the old
FAQ content into other sections of the documentation).

Signed-off-by: Jeff Squyres &lt;jsquyres@cisco.com&gt;
diff --git a/docs/faq/building-open-mpi.rst b/docs/faq/building-open-mpi.rst
@@ -1,7 +1,18 @@
 Building Open MPI
 =================
 
-.. TODO How can I create a TOC just for this page here at the top?
+.. error:: This section represents old content from the <= v4.x FAQ
+           that has not been properly converted to the new-style
+           documentation.  The content here was perfunctorily
+           converted to RST, but it still needs to be:
+
+           #. Converted from a question-and-answer style to a regular
+              documentation style (like the rest of these docs).
+           #. Removed from this section and folded into other sections
+              in these docs.
+
+           To be clear, this section will eventually be deleted; do
+           not write any new content in this section.
 
 /////////////////////////////////////////////////////////////////////////
 
diff --git a/docs/faq/fault-tolerance.rst b/docs/faq/fault-tolerance.rst
@@ -1,6 +1,21 @@
 Fault Tolerance
 ===============
 
+.. error:: This section represents old content from the <= v4.x FAQ
+           that has not been properly converted to the new-style
+           documentation.  The content here was perfunctorily
+           converted to RST, but it still needs to be:
+
+           #. Converted from a question-and-answer style to a regular
+              documentation style (like the rest of these docs).
+           #. Removed from this section and folded into other sections
+              in these docs.
+
+           To be clear, this section will eventually be deleted; do
+           not write any new content in this section.
+
+/////////////////////////////////////////////////////////////////////////
+
 What is "fault tolerance"?
 --------------------------
 
diff --git a/docs/faq/general-tuning.rst b/docs/faq/general-tuning.rst
@@ -1,7 +1,18 @@
 General Tuning
 ==============
 
-.. TODO How can I create a TOC just for this page here at the top?
+.. error:: This section represents old content from the <= v4.x FAQ
+           that has not been properly converted to the new-style
+           documentation.  The content here was perfunctorily
+           converted to RST, but it still needs to be:
+
+           #. Converted from a question-and-answer style to a regular
+              documentation style (like the rest of these docs).
+           #. Removed from this section and folded into other sections
+              in these docs.
+
+           To be clear, this section will eventually be deleted; do
+           not write any new content in this section.
 
 /////////////////////////////////////////////////////////////////////////
 
diff --git a/docs/faq/index.rst b/docs/faq/index.rst
@@ -1,12 +1,18 @@
-.. Open MPI FAQ
+Frequently Asked Questions (FAQ)
+================================
 
-   This page will likely eventually go away (i.e., the "FAQ" section
-   will likely disappear -- its contents will likely just be folded in
-   elsewhere in the document).
+.. error:: This section represents old content from the <= v4.x FAQ
+           that has not been properly converted to the new-style
+           documentation.  The content here was perfunctorily
+           converted to RST, but it still needs to be:
 
+           #. Converted from a question-and-answer style to a regular
+              documentation style (like the rest of these docs).
+           #. Removed from this section and folded into other sections
+              in these docs.
 
-Frequently Asked Questions (FAQ)
-================================
+           To be clear, this section will eventually be deleted; do
+           not write any new content in this section.
 
 The pages below include questions that we are asked frequently enough
 that they are worth categorizing in an official way.
diff --git a/docs/faq/large-clusters.rst b/docs/faq/large-clusters.rst
@@ -1,7 +1,18 @@
 Large Clusters
 ==============
 
-.. TODO How can I create a TOC just for this page here at the top?
+.. error:: This section represents old content from the <= v4.x FAQ
+           that has not been properly converted to the new-style
+           documentation.  The content here was perfunctorily
+           converted to RST, but it still needs to be:
+
+           #. Converted from a question-and-answer style to a regular
+              documentation style (like the rest of these docs).
+           #. Removed from this section and folded into other sections
+              in these docs.
+
+           To be clear, this section will eventually be deleted; do
+           not write any new content in this section.
 
 /////////////////////////////////////////////////////////////////////////
 
diff --git a/docs/faq/running-mpi-apps.rst b/docs/faq/running-mpi-apps.rst
@@ -1,7 +1,18 @@
 Running MPI applications
 ========================
 
-.. TODO How can I create a TOC just for this page here at the top?
+.. error:: This section represents old content from the <= v4.x FAQ
+           that has not been properly converted to the new-style
+           documentation.  The content here was perfunctorily
+           converted to RST, but it still needs to be:
+
+           #. Converted from a question-and-answer style to a regular
+              documentation style (like the rest of these docs).
+           #. Removed from this section and folded into other sections
+              in these docs.
+
+           To be clear, this section will eventually be deleted; do
+           not write any new content in this section.
 
 /////////////////////////////////////////////////////////////////////////
 
diff --git a/docs/faq/supported-systems.rst b/docs/faq/supported-systems.rst
@@ -1,7 +1,18 @@
 Supported systems
 =================
 
-.. TODO How can I create a TOC just for this page here at the top?
+.. error:: This section represents old content from the <= v4.x FAQ
+           that has not been properly converted to the new-style
+           documentation.  The content here was perfunctorily
+           converted to RST, but it still needs to be:
+
+           #. Converted from a question-and-answer style to a regular
+              documentation style (like the rest of these docs).
+           #. Removed from this section and folded into other sections
+              in these docs.
+
+           To be clear, this section will eventually be deleted; do
+           not write any new content in this section.
 
 /////////////////////////////////////////////////////////////////////////
 
diff --git a/docs/faq/sysadmin.rst b/docs/faq/sysadmin.rst
@@ -1,7 +1,18 @@
 System administrator-level technical information
 ================================================
 
-.. TODO How can I create a TOC just for this page here at the top?
+.. error:: This section represents old content from the <= v4.x FAQ
+           that has not been properly converted to the new-style
+           documentation.  The content here was perfunctorily
+           converted to RST, but it still needs to be:
+
+           #. Converted from a question-and-answer style to a regular
+              documentation style (like the rest of these docs).
+           #. Removed from this section and folded into other sections
+              in these docs.
+
+           To be clear, this section will eventually be deleted; do
+           not write any new content in this section.
 
 /////////////////////////////////////////////////////////////////////////
 
diff --git a/docs/faq/troubleshooting.rst b/docs/faq/troubleshooting.rst
@@ -1,7 +1,18 @@
 Troubleshooting
 ===============
 
-.. TODO How can I create a TOC just for this page here at the top?
+.. error:: This section represents old content from the <= v4.x FAQ
+           that has not been properly converted to the new-style
+           documentation.  The content here was perfunctorily
+           converted to RST, but it still needs to be:
+
+           #. Converted from a question-and-answer style to a regular
+              documentation style (like the rest of these docs).
+           #. Removed from this section and folded into other sections
+              in these docs.
+
+           To be clear, this section will eventually be deleted; do
+           not write any new content in this section.
 
 /////////////////////////////////////////////////////////////////////////
 
