diff --git a/.gitignore b/.gitignore index 1e5e0bdf7cf..2212db1fa92 100644 --- a/.gitignore +++ b/.gitignore @@ -784,3 +784,5 @@ test/util/bipartite_graph opal/test/reachable/reachable_netlink opal/test/reachable/reachable_weighted + +docs/_build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000000..6debda93fef --- /dev/null +++ b/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 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000000..db269e9ea94 --- /dev/null +++ b/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} +""" diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000000..68169377f0a --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,47 @@ +.. image:: openmpi_logo.png + :align: right + +Open MPI |ompi_series| +====================== + +`The Open MPI Project `_ is an open source +implementation of the `Message Passing Interface (MPI) specification +`_ 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 `_ + and the README file in the source tarball. + + For example: + + * `v4.1.x README file `_ + * `v4.0.x README file `_ + +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. diff --git a/docs/openmpi_logo.png b/docs/openmpi_logo.png new file mode 100644 index 00000000000..16a2e0cbab2 Binary files /dev/null and b/docs/openmpi_logo.png differ