python: publish sphinx docs to read the docs
Background:
This is a follow-up to the PR that adds sphinx docs.
Read the Docs is a hosting platform for documentation, primarily Python
docs. It supports builds at commit time as well as at specific git
labels to support versioned docs. I have claimed the
protobuf.readthedocs.io project and can add any Googlers who need access
to be able to configure and trigger builds.
https://readthedocs.org/projects/protobuf/builds/ It's also relatively
easy to create a new project to test the documentation builds from a
fork, such as https://readthedocs.org/projects/tswast-protobuf/builds/
About this change:
Once web hooks are configured, Read the Docs will automatically build
the docs for the latest changes on the master branch.
I needed to update `python/setup.py` to support installation from the
root of the repository because Read the Docs does not `cd python` before
installing the protobuf package with `setup.py install`. To support
this, I updated the file paths to use the absolute path to files. The
`__file__` special variable comes in handy for this, as it provides the
path to the `setup.py` file.
A banner is added to the docs when published to readthedocs. This links
to the official documentation and the future home of the stable API
reference on googleapis.dev.
diff --git a/python/docs/conf.py b/python/docs/conf.py
index 0b42b55..6aef7e4 100644
--- a/python/docs/conf.py
+++ b/python/docs/conf.py
@@ -41,7 +41,7 @@
# 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 os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
import google.protobuf
@@ -69,6 +69,7 @@
# ones.
extensions = [
"sphinx.ext.autosummary",
+ "sphinx.ext.ifconfig",
"sphinx.ext.intersphinx",
"sphinxcontrib.napoleon",
]
@@ -237,3 +238,17 @@
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {"https://docs.python.org/": None}
+
+# -- Config values -----------------------------------------------------------
+# The setup() function is needed to add configuration values to the Sphinx
+# builder. We use this to show a banner when built on Read the Docs.
+# https://www.sphinx-doc.org/en/master/usage/extensions/ifconfig.html
+
+def setup(app):
+ app.add_config_value(
+ "build_env",
+ # Read the Docs sets a READTHEDOCS environment during builds.
+ # https://docs.readthedocs.io/en/stable/builds.html#build-environment
+ "readthedocs" if os.getenv("READTHEDOCS") else "",
+ "env"
+ )
