diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000000..88f4c100f3 --- /dev/null +++ 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 index 0b42b55d50..6aef7e483c 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 @@ release = google.protobuf.__version__ # ones. extensions = [ "sphinx.ext.autosummary", + "sphinx.ext.ifconfig", "sphinx.ext.intersphinx", "sphinxcontrib.napoleon", ] @@ -237,3 +238,17 @@ autosummary_generate = True # 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 index 9b76e0cac1..07debedd18 100755 --- a/python/docs/generate_docs.py +++ b/python/docs/generate_docs.py @@ -95,6 +95,18 @@ TOC_TEMPLATE = """.. START REFTOC, generated by generate_docs.py. 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + {module} {underline} diff --git a/python/docs/google/protobuf.rst b/python/docs/google/protobuf.rst index 0982bf31a8..b26102e110 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf =============== diff --git a/python/docs/google/protobuf/any_pb2.rst b/python/docs/google/protobuf/any_pb2.rst index 42198c8cf6..b6f47ef3fd 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.any_pb2 ======================= diff --git a/python/docs/google/protobuf/descriptor.rst b/python/docs/google/protobuf/descriptor.rst index 949b97f61a..29b07746f4 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.descriptor ========================== diff --git a/python/docs/google/protobuf/descriptor_database.rst b/python/docs/google/protobuf/descriptor_database.rst index 912439d1f7..1b8b3904d8 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.descriptor_database =================================== diff --git a/python/docs/google/protobuf/descriptor_pb2.rst b/python/docs/google/protobuf/descriptor_pb2.rst index 6b18b44bb9..94eec35c34 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.descriptor_pb2 ============================== diff --git a/python/docs/google/protobuf/descriptor_pool.rst b/python/docs/google/protobuf/descriptor_pool.rst index 8b1ab9943a..c2ee33e7b3 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.descriptor_pool =============================== diff --git a/python/docs/google/protobuf/duration_pb2.rst b/python/docs/google/protobuf/duration_pb2.rst index 7e39f9e94e..4233e3cb52 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.duration_pb2 ============================ diff --git a/python/docs/google/protobuf/empty_pb2.rst b/python/docs/google/protobuf/empty_pb2.rst index 39cbb6431e..c386a4c5c9 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.empty_pb2 ========================= diff --git a/python/docs/google/protobuf/field_mask_pb2.rst b/python/docs/google/protobuf/field_mask_pb2.rst index 3a0c40cd3b..d9d807069e 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.field_mask_pb2 ============================== diff --git a/python/docs/google/protobuf/json_format.rst b/python/docs/google/protobuf/json_format.rst index 8f436e154d..eb3b0c5399 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.json_format =========================== diff --git a/python/docs/google/protobuf/message.rst b/python/docs/google/protobuf/message.rst index 03d0dda86f..a20424807c 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.message ======================= diff --git a/python/docs/google/protobuf/message_factory.rst b/python/docs/google/protobuf/message_factory.rst index b098a8d392..93183cc03d 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.message_factory =============================== diff --git a/python/docs/google/protobuf/proto_builder.rst b/python/docs/google/protobuf/proto_builder.rst index 5cc17409d3..36243a2fff 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.proto_builder ============================= diff --git a/python/docs/google/protobuf/reflection.rst b/python/docs/google/protobuf/reflection.rst index 0bee3e5f45..d177fc02f6 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.reflection ========================== diff --git a/python/docs/google/protobuf/service.rst b/python/docs/google/protobuf/service.rst index 9b3a7b3267..6d71f81088 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.service ======================= diff --git a/python/docs/google/protobuf/service_reflection.rst b/python/docs/google/protobuf/service_reflection.rst index 1fb688531e..30f30dd293 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.service_reflection ================================== diff --git a/python/docs/google/protobuf/struct_pb2.rst b/python/docs/google/protobuf/struct_pb2.rst index 617a580f78..9179eede3c 100644 --- 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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.struct_pb2 ========================== diff --git a/python/docs/google/protobuf/symbol_database.rst b/python/docs/google/protobuf/symbol_database.rst index 76bcf2f4e5..6ea73522f5 100644 --- a/python/docs/google/protobuf/symbol_database.rst +++ b/python/docs/google/protobuf/symbol_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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.symbol_database =============================== diff --git a/python/docs/google/protobuf/text_encoding.rst b/python/docs/google/protobuf/text_encoding.rst index 0e3a5d97ba..a2eb959dc0 100644 --- a/python/docs/google/protobuf/text_encoding.rst +++ b/python/docs/google/protobuf/text_encoding.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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.text_encoding ============================= diff --git a/python/docs/google/protobuf/text_format.rst b/python/docs/google/protobuf/text_format.rst index 6b4c40a661..686b8fc002 100644 --- a/python/docs/google/protobuf/text_format.rst +++ b/python/docs/google/protobuf/text_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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.text_format =========================== diff --git a/python/docs/google/protobuf/timestamp_pb2.rst b/python/docs/google/protobuf/timestamp_pb2.rst index 4160fe0731..540df8395d 100644 --- a/python/docs/google/protobuf/timestamp_pb2.rst +++ b/python/docs/google/protobuf/timestamp_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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.timestamp_pb2 ============================= diff --git a/python/docs/google/protobuf/type_pb2.rst b/python/docs/google/protobuf/type_pb2.rst index 8f0fb1481c..e9b19d7b85 100644 --- a/python/docs/google/protobuf/type_pb2.rst +++ b/python/docs/google/protobuf/type_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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.type_pb2 ======================== diff --git a/python/docs/google/protobuf/wrappers_pb2.rst b/python/docs/google/protobuf/wrappers_pb2.rst index 037af966f0..8f29aa7838 100644 --- a/python/docs/google/protobuf/wrappers_pb2.rst +++ b/python/docs/google/protobuf/wrappers_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 + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + google.protobuf.wrappers_pb2 ============================ diff --git a/python/docs/index.rst b/python/docs/index.rst index d5bb39e780..57f7ce70ce 100644 --- a/python/docs/index.rst +++ b/python/docs/index.rst @@ -3,6 +3,18 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. ifconfig:: build_env == 'readthedocs' + + .. warning:: + + You are reading the documentation for the `latest committed changes + `_ of + the `Protocol Buffers package for Python + `_. + Some features may not yet be released. Read the documentation for the + latest released package at `googleapis.dev + `_. + Protocol Buffers Python API Reference ===================================== diff --git a/python/setup.py b/python/setup.py index 9aabbf7aaa..d478858525 100755 --- a/python/setup.py +++ b/python/setup.py @@ -19,17 +19,23 @@ from distutils.command.build_py import build_py as _build_py from distutils.command.clean import clean as _clean from distutils.spawn import find_executable + +current_dir = os.path.dirname(__file__) +current_dir_relative = os.path.relpath(current_dir) +src_dir = os.path.abspath(os.path.join(current_dir, "..", "src")) +vsprojects_dir = os.path.abspath(os.path.join(current_dir, "..", "vsprojects")) + # Find the Protocol Compiler. if 'PROTOC' in os.environ and os.path.exists(os.environ['PROTOC']): protoc = os.environ['PROTOC'] -elif os.path.exists("../src/protoc"): - protoc = "../src/protoc" -elif os.path.exists("../src/protoc.exe"): - protoc = "../src/protoc.exe" -elif os.path.exists("../vsprojects/Debug/protoc.exe"): - protoc = "../vsprojects/Debug/protoc.exe" -elif os.path.exists("../vsprojects/Release/protoc.exe"): - protoc = "../vsprojects/Release/protoc.exe" +elif os.path.exists(os.path.join(src_dir, "protoc")): + protoc = os.path.join(src_dir, "protoc") +elif os.path.exists(os.path.join(src_dir, "protoc.exe")): + protoc = os.path.join(src_dir, "protoc.exe") +elif os.path.exists(os.path.join(vsprojects_dir, "Debug", "protoc.exe")): + protoc = os.path.join(vsprojects_dir, "Debug", "protoc.exe") +elif os.path.exists(os.path.join(vsprojects_dir, "Release", "protoc.exe")): + protoc = os.path.join(vsprojects_dir, "Release", "protoc.exe") else: protoc = find_executable("protoc") @@ -40,7 +46,7 @@ def GetVersion(): Do not import google.protobuf.__init__ directly, because an installed protobuf library may be loaded instead.""" - with open(os.path.join('google', 'protobuf', '__init__.py')) as version_file: + with open(os.path.join(current_dir, 'google', 'protobuf', '__init__.py')) as version_file: exec(version_file.read(), globals()) global __version__ return __version__ @@ -51,15 +57,21 @@ def generate_proto(source, require = True): .proto file. Does nothing if the output already exists and is newer than the input.""" + original_source = source + source = source.replace("../src", src_dir) + if not require and not os.path.exists(source): return - output = source.replace(".proto", "_pb2.py").replace("../src/", "") + output = os.path.join( + current_dir, + original_source.replace(".proto", "_pb2.py").replace("../src/", "") + ) if (not os.path.exists(output) or (os.path.exists(source) and os.path.getmtime(source) > os.path.getmtime(output))): - print("Generating %s..." % output) + print("Generating %s..." % os.path.relpath(output)) if not os.path.exists(source): sys.stderr.write("Can't find required file: %s\n" % source) @@ -71,7 +83,13 @@ def generate_proto(source, require = True): "or install the binary package.\n") sys.exit(-1) - protoc_command = [ protoc, "-I../src", "-I.", "--python_out=.", source ] + protoc_command = [ + protoc, + "-I{}".format(src_dir), + "-I{}".format(current_dir), + "--python_out={}".format(current_dir), + source, + ] if subprocess.call(protoc_command) != 0: sys.exit(-1) @@ -116,7 +134,7 @@ def GenerateUnittestProtos(): class clean(_clean): def run(self): # Delete generated files in the code tree. - for (dirpath, dirnames, filenames) in os.walk("."): + for (dirpath, dirnames, filenames) in os.walk(current_dir): for filename in filenames: filepath = os.path.join(dirpath, filename) if filepath.endswith("_pb2.py") or filepath.endswith(".pyc") or \ @@ -269,7 +287,14 @@ if __name__ == '__main__': "Programming Language :: Python :: 3.7", ], namespace_packages=['google'], + # package_dir is required when setup.py is not run from the python/ + # directory (such as from the ReadTheDocs build). See + # https://setuptools.readthedocs.io/en/latest/setuptools.html#using-find-packages + # package_dir must be a relative path. See: + # https://stackoverflow.com/a/53547931/101923 + package_dir={"": current_dir_relative}, packages=find_packages( + where=current_dir, exclude=[ 'import_test_package', ],