oss_28_fix_sphinx_docs_build

[ocelotl]

Fix the broken Sphinx docs build: Zipkin proto autodoc protobuf conflict (D1) and empty OpenCensus exporter page (D2) (Linear OSS-28).

Branch / worktree: oss_28_fix_sphinx_docs_build

Linear issue: https://linear.app/dash0/issue/OSS-28/d1-d2-fix-broken-sphinx-docs-build-zipkin-protobuf-conflict-opencensus

[ocelotl]

🔒 Internal (dash0) — not for upstream.

• Linear: https://linear.app/dash0/issue/OSS-28/d1-d2-fix-broken-sphinx-docs-build-zipkin-protobuf-conflict-opencensus (D1/D2)
• Slug/branch/worktree: oss_28_fix_sphinx_docs_build
• Commit: 9716beb1a · PR: oss_28_fix_sphinx_docs_build #46
• Validation: supervisor confirmed scope (docs + docs-requirements + opencensus pyproject + changelog); worker ran sphinx-build -E -a -W → exit 0, zipkin documented, opencensus page 6 objects.
• Reviewer note: widening the opencensus protobuf ~=3.13 pin to >=3.13,<8.0 was required (old pin made the docs install unresolvable vs opentelemetry-proto's protobuf>=5.0); this is a real (small) source-constraint change beyond docs config.

[ocelotl]

📣 Public-facing draft — to be opened upstream in open-telemetry/opentelemetry-python. No internal references; copy verbatim.

Title: Sphinx docs build is broken: zipkin-proto exporter fails autodoc and OpenCensus exporter page is empty

The documentation build has two independent defects.

1. zipkin-proto-http breaks the -W build

exporter/opentelemetry-exporter-zipkin-proto-http/pyproject.toml pins protobuf ~= 3.12, but the docs build installs a modern protobuf (docs-requirements.txt → protobuf==5.29.6). The checked-in generated .../v2/gen/zipkin_pb2.py uses the old _descriptor.FileDescriptor(...) style, which under the modern protobuf C++/upb runtime raises TypeError: Descriptors cannot be created directly, so autodoc skips the module — the sole -W failure. (The tox docs env sets PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python, but .readthedocs.yml invokes sphinx directly and does not, so the RTD build is still exposed.)

2. OpenCensus exporter page renders 0 objects

docs/exporter/opencensus/opencensus.rst autodocs opentelemetry.exporter.opencensus, but opentelemetry-exporter-opencensus is not in docs-requirements.txt (only the shim is), so autodoc cannot import it. Also, the top-level package __init__.py has only a docstring — OpenCensusSpanExporter lives in the trace_exporter submodule, which the rst doesn't reference.

Proposed fix

• D1: set PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python in docs/conf.py (via os.environ.setdefault) so every sphinx invocation, including RTD, is covered.
• D2: add ./exporter/opentelemetry-exporter-opencensus to docs-requirements.txt, document the trace_exporter submodule in the rst, and widen the exporter's protobuf ~= 3.13 pin (which otherwise makes the docs install unresolvable against opentelemetry-proto's protobuf >= 5.0) to >= 3.13, < 8.0 (verified to import/run under protobuf 5).