Merge pull request protocolbuffers#7150 from tswast/issue4498-readthe…

…docs python: publish sphinx docs to read the docs
CauhxMilloy · Feb 29, 2020 · 4ff0fb8 · 4ff0fb8
2 parents ed19442 + 35a2bf9
commit 4ff0fb8
Show file tree

Hide file tree

Showing 28 changed files with 376 additions and 14 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,22 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+sphinx:
+  configuration: python/docs/conf.py
+  fail_on_warning: false
+
+# Setup build requirements for docs.
+# Use conda so that we can install the latest libprotobuf package without
+# having to build from scratch just for docs builds.
+conda:
+  environment: python/docs/environment.yml
+
+python:
+  version: 3.7
+  install:
+    - method: setuptools
+      path: python
diff --git 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"
+  )
diff --git a/python/docs/generate_docs.py b/python/docs/generate_docs.py
@@ -95,6 +95,18 @@
 
 AUTOMODULE_TEMPLATE = """.. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 {module}
 {underline}
 

diff --git a/python/docs/google/protobuf.rst b/python/docs/google/protobuf.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf
 ===============
 

diff --git a/python/docs/google/protobuf/any_pb2.rst b/python/docs/google/protobuf/any_pb2.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.any_pb2
 =======================
 

diff --git a/python/docs/google/protobuf/descriptor.rst b/python/docs/google/protobuf/descriptor.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.descriptor
 ==========================
 

diff --git a/python/docs/google/protobuf/descriptor_database.rst b/python/docs/google/protobuf/descriptor_database.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.descriptor_database
 ===================================
 

diff --git a/python/docs/google/protobuf/descriptor_pb2.rst b/python/docs/google/protobuf/descriptor_pb2.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.descriptor_pb2
 ==============================
 

diff --git a/python/docs/google/protobuf/descriptor_pool.rst b/python/docs/google/protobuf/descriptor_pool.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.descriptor_pool
 ===============================
 

diff --git a/python/docs/google/protobuf/duration_pb2.rst b/python/docs/google/protobuf/duration_pb2.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.duration_pb2
 ============================
 

diff --git a/python/docs/google/protobuf/empty_pb2.rst b/python/docs/google/protobuf/empty_pb2.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.empty_pb2
 =========================
 

diff --git a/python/docs/google/protobuf/field_mask_pb2.rst b/python/docs/google/protobuf/field_mask_pb2.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.field_mask_pb2
 ==============================
 

diff --git a/python/docs/google/protobuf/json_format.rst b/python/docs/google/protobuf/json_format.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.json_format
 ===========================
 

diff --git a/python/docs/google/protobuf/message.rst b/python/docs/google/protobuf/message.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.message
 =======================
 

diff --git a/python/docs/google/protobuf/message_factory.rst b/python/docs/google/protobuf/message_factory.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.message_factory
 ===============================
 

diff --git a/python/docs/google/protobuf/proto_builder.rst b/python/docs/google/protobuf/proto_builder.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.proto_builder
 =============================
 

diff --git a/python/docs/google/protobuf/reflection.rst b/python/docs/google/protobuf/reflection.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.reflection
 ==========================
 

diff --git a/python/docs/google/protobuf/service.rst b/python/docs/google/protobuf/service.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.service
 =======================
 

diff --git a/python/docs/google/protobuf/service_reflection.rst b/python/docs/google/protobuf/service_reflection.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.service_reflection
 ==================================
 

diff --git a/python/docs/google/protobuf/struct_pb2.rst b/python/docs/google/protobuf/struct_pb2.rst
@@ -1,5 +1,17 @@
 .. DO NOT EDIT, generated by generate_docs.py.
 
+.. ifconfig:: build_env == 'readthedocs'
+
+   .. warning::
+
+      You are reading the documentation for the `latest committed changes
+      <https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
+      the `Protocol Buffers package for Python
+      <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
+      Some features may not yet be released. Read the documentation for the
+      latest released package at `googleapis.dev
+      <https://googleapis.dev/python/protobuf/latest/>`_.
+
 google.protobuf.struct_pb2
 ==========================