From 9716beb1a3dfc609309b64a6c8e8f1c627e90c59 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Wed, 22 Jul 2026 01:33:29 -0500 Subject: [PATCH 1/2] Fix broken Sphinx docs build for zipkin proto and opencensus exporters The docs build installs a modern protobuf (5.x) but the zipkin-proto-http exporter ships protobuf code generated for the old runtime. Under the C++ protobuf implementation that code raises "Descriptors cannot be created directly", so autodoc silently skips the module and the -W build fails. Force the pure-Python protobuf implementation in docs/conf.py via os.environ.setdefault so the module is importable for autodoc regardless of how sphinx-build is invoked (including the Read the Docs path, which does not go through tox). The opencensus exporter documentation page rendered zero objects because opentelemetry-exporter-opencensus was not installed for the docs build (only the shim was). Add it to docs-requirements.txt and document its trace_exporter submodule in the rst so the OpenCensusSpanExporter API is rendered. Its protobuf pin (~= 3.13) conflicted with opentelemetry-proto (>= 5.0) and made the docs install unresolvable, so widen it to >= 3.13, < 8.0; the exporter imports and runs correctly under protobuf 5. --- .changelog/0000.fixed | 4 ++++ docs-requirements.txt | 1 + docs/conf.py | 8 ++++++++ docs/exporter/opencensus/opencensus.rst | 5 +++++ exporter/opentelemetry-exporter-opencensus/pyproject.toml | 2 +- 5 files changed, 19 insertions(+), 1 deletion(-) create mode 100644 .changelog/0000.fixed diff --git a/.changelog/0000.fixed b/.changelog/0000.fixed new file mode 100644 index 00000000000..a6f35985c71 --- /dev/null +++ b/.changelog/0000.fixed @@ -0,0 +1,4 @@ +Fix the Sphinx docs build: force the pure-Python protobuf implementation in +`docs/conf.py` so the zipkin-proto-http exporter can be documented, and add +`opentelemetry-exporter-opencensus` to the docs requirements (widening its +`protobuf` constraint to allow protobuf 5) so its API reference renders diff --git a/docs-requirements.txt b/docs-requirements.txt index 4cbce8432ed..53af1b8dd1c 100644 --- a/docs-requirements.txt +++ b/docs-requirements.txt @@ -13,6 +13,7 @@ sphinx-jekyll-builder==0.3.0 ./opentelemetry-proto-json ./shim/opentelemetry-opencensus-shim ./shim/opentelemetry-opentracing-shim +./exporter/opentelemetry-exporter-opencensus ./exporter/opentelemetry-exporter-otlp-proto-common ./exporter/opentelemetry-exporter-otlp-proto-http ./exporter/opentelemetry-exporter-otlp-proto-grpc diff --git a/docs/conf.py b/docs/conf.py index 01b386beacc..e2e5c8a6006 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,6 +18,14 @@ from os import listdir from os.path import isdir, join +# The zipkin-proto-http exporter pins protobuf ~= 3.12, but the docs build +# installs a modern protobuf (see docs-requirements.txt). Generated *_pb2.py +# modules built against the old runtime raise "Descriptors cannot be created +# directly" when imported under the C++ implementation of the newer runtime, +# which makes autodoc silently skip the module. Forcing the pure-Python +# protobuf implementation avoids that error so the module can be documented. +os.environ.setdefault("PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION", "python") + # configure django to avoid the following exception: # django.core.exceptions.ImproperlyConfigured: Requested settings, but settings # are not configured. You must either define the environment variable diff --git a/docs/exporter/opencensus/opencensus.rst b/docs/exporter/opencensus/opencensus.rst index 6bdcd6a873c..e34fc1633fc 100644 --- a/docs/exporter/opencensus/opencensus.rst +++ b/docs/exporter/opencensus/opencensus.rst @@ -5,3 +5,8 @@ OpenCensus Exporter :members: :undoc-members: :show-inheritance: + +.. automodule:: opentelemetry.exporter.opencensus.trace_exporter + :members: + :undoc-members: + :show-inheritance: diff --git a/exporter/opentelemetry-exporter-opencensus/pyproject.toml b/exporter/opentelemetry-exporter-opencensus/pyproject.toml index 86dc7ee07e7..98afc3e1370 100644 --- a/exporter/opentelemetry-exporter-opencensus/pyproject.toml +++ b/exporter/opentelemetry-exporter-opencensus/pyproject.toml @@ -33,7 +33,7 @@ dependencies = [ "opencensus-proto >= 0.1.0, < 1.0.0", "opentelemetry-api >= 1.45.0.dev", "opentelemetry-sdk >= 1.15", - "protobuf ~= 3.13", + "protobuf >= 3.13, < 8.0", "setuptools >= 16.0", ] From 7e7dffcd873ce1899d990eb331ff6ba872fdd4a9 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Wed, 22 Jul 2026 08:38:13 -0500 Subject: [PATCH 2/2] Rename changelog fragment to match PR number --- .changelog/{0000.fixed => 46.fixed} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .changelog/{0000.fixed => 46.fixed} (100%) diff --git a/.changelog/0000.fixed b/.changelog/46.fixed similarity index 100% rename from .changelog/0000.fixed rename to .changelog/46.fixed