oss_28_fix_sphinx_docs_build

[ocelotl]

Closes #39

Fix the broken Sphinx -W docs build (Linear OSS-28, D1/D2): force pure-Python protobuf in docs/conf.py so the zipkin generated pb2 module autodocs under modern protobuf (D1); add opentelemetry-exporter-opencensus to docs-requirements + document its trace_exporter submodule + widen its protobuf constraint (>=3.13,<8.0) so the docs install resolves (D2).

Validation: verified via a real sphinx-build -E -a -W run — exits 0; zipkin proto module documented; opencensus page renders 6 objects (was 0). Scope: docs/ + docs-requirements + opencensus pyproject + changelog.

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)
• Closes: oss_28_fix_sphinx_docs_build #39 · Branch: oss_28_fix_sphinx_docs_build · Commit: 9716beb1a
• Validation: sphinx-build -E -a -W exit 0 (zipkin documented; opencensus page 6 objects). Scope docs + docs-requirements + opencensus pyproject + changelog.

[ocelotl]

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

Title: Fix broken Sphinx docs build for zipkin proto and opencensus exporters

What

Fix the documentation build so sphinx-build -W succeeds, the zipkin-proto-http exporter is documented, and the OpenCensus exporter page renders its API.

Why

• The zipkin-proto-http generated zipkin_pb2.py (old descriptor style) raises Descriptors cannot be created directly under the modern protobuf runtime installed for docs, so autodoc drops the module and the -W build fails. The tox docs env works around this with an env var, but the Read the Docs build (which calls sphinx directly) does not.
• The OpenCensus exporter doc page rendered zero objects: the package was never installed for docs (only the shim was), and the rst referenced the empty top-level package rather than the trace_exporter submodule that holds OpenCensusSpanExporter.

How

• Set PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python in docs/conf.py via os.environ.setdefault, so the fix applies regardless of how sphinx is invoked (tox and RTD).
• Add opentelemetry-exporter-opencensus to docs-requirements.txt and an automodule for its trace_exporter submodule in the rst.
• Widen the opencensus exporter's protobuf constraint from ~= 3.13 to >= 3.13, < 8.0; the old pin conflicts with opentelemetry-proto (>= 5.0) and made the docs install unresolvable. The exporter imports/runs under protobuf 5.

How verified

Ran sphinx-build -E -a -W -b html -T with the external env var unset — build succeeds (exit 0). The zipkin proto exporter is documented, and the OpenCensus page renders its objects including OpenCensusSpanExporter (previously 0). Confirmed pip install -r docs-requirements.txt resolves with all changes.

[github-actions]

This PR has been automatically marked as stale because it has not had any activity for 14 days. It will be closed if no further activity occurs within 14 days of this comment.
If you're still working on this, please add a comment or push new commits.