Merge pull request #10112 from jsquyres/pr/v4.1.x/skeleton-readthedocs

v4.1.x: Add skeleton ReadTheDocs docs for the v4.1.x branch

.gitignore

@@ -784,3 +784,5 @@ test/util/bipartite_graph
 
 opal/test/reachable/reachable_netlink
 opal/test/reachable/reachable_weighted
+
+docs/_build

docs/Makefile

@@ -0,0 +1,23 @@
+#
+# Copyright (c) 2022 Cisco Systems, Inc.  All rights reserved.
+#
+# $COPYRIGHT$
+#
+# Additional copyrights may follow
+#
+# $HEADER$
+#
+
+# This directory is not included in Open MPI distribution tarballs.
+# Its only purpose is to be built by readthedocs.io in order to show a
+# skeleton "This version of Open MPI does not have RTD docs / see
+# these other places for docs for this version of Open MPI".
+
+OUTDIR             = _build
+SPHINX_CONFIG      = conf.py
+SPHINX_OPTS       ?= -W --keep-going
+
+all:
+	sphinx-build -M html "$(srcdir)" "$(OUTDIR)" $(SPHINX_OPTS)
+
+.PHONY: all

docs/conf.py

@@ -0,0 +1,88 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- Project information -----------------------------------------------------
+
+import datetime
+year = datetime.datetime.now().year
+
+project = 'Open MPI'
+copyright = f'2003-{year}, The Open MPI Community'
+author = 'The Open MPI Community'
+
+with open("../VERSION") as fp:
+    ompi_lines = fp.readlines()
+
+ompi_data = dict()
+for ompi_line in ompi_lines:
+    if '#' in ompi_line:
+        parts = ompi_line.split("#")
+        ompi_line = parts[0]
+    ompi_line = ompi_line.strip()
+
+    if '=' not in ompi_line:
+        continue
+
+    ompi_key, ompi_val = ompi_line.split("=")
+    ompi_data[ompi_key.strip()] = ompi_val.strip()
+
+# "release" is a sphinx config variable -- assign it to the computed
+# Open MPI version number.
+series = f"{ompi_data['major']}.{ompi_data['minor']}.x"
+release = f"{ompi_data['major']}.{ompi_data['minor']}.{ompi_data['release']}{ompi_data['greek']}"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+import sphinx_rtd_theme
+extensions = ['recommonmark', "sphinx_rtd_theme"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv', 'py*/**']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+# -- Open MPI-specific options -----------------------------------------------
+
+# This prolog is included in every file.  Put common stuff here.
+
+rst_prolog = f"""
+.. |mdash|  unicode:: U+02014 .. Em dash
+.. |rarrow| unicode:: U+02192 .. Right arrow
+
+.. |year| replace:: {year}
+.. |ompi_ver| replace:: v{release}
+.. |ompi_series| replace:: v{series}
+"""

docs/index.rst

@@ -0,0 +1,47 @@
+.. image:: openmpi_logo.png
+   :align: right
+
+Open MPI |ompi_series|
+======================
+
+`The Open MPI Project <https://www.open-mpi.org/>`_ is an open source
+implementation of the `Message Passing Interface (MPI) specification
+<https://www.mpi-forum.org/docs/>`_ that is developed and maintained
+by a consortium of academic, research, and industry partners.  Open
+MPI is therefore able to combine the expertise, technologies, and
+resources from all across the High Performance Computing community in
+order to build the best MPI library available.  Open MPI offers
+advantages for system and software vendors, application developers and
+computer science researchers.
+
+Documentation locations
+=======================
+
+Documentation for Open can be found in the following locations:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Open MPI version
+     - Documentation location
+
+   * - v5.0.0 and later
+     - Open MPI documentation has consolidated and moved to
+
+       https://docs.open-mpi.org/.
+
+   * - v4.1.x and earlier
+     - See the `legacy Open MPI FAQ <https://www.open-mpi.org/faq/>`_
+       and the README file in the source tarball.
+
+       For example:
+
+       * `v4.1.x README file <https://github.com/open-mpi/ompi/blob/v4.1.x/README>`_
+       * `v4.0.x README file <https://github.com/open-mpi/ompi/blob/v4.0.x/README>`_
+
+Nothing to see here
+===================
+
+This page only exists to emphasize that the Open MPI |ompi_series|
+documentation does *not* exist here.  All Open MPI documentation prior
+to v5.0.0 exists in the legacy locations listed above.