docs: add missing modules to sphinx documentation build by raajheshkannaa · Pull Request #5017 · open-telemetry/opentelemetry-python

raajheshkannaa · 2026-03-28T02:37:02Z

Closes #2573

Summary

Adds RST files for 5 Python modules that were missing from the sphinx doc build
Updates toctree entries in index and parent RST files so the new pages are reachable

Modules added

API:

opentelemetry._events - Events API (EventLogger, EventLoggerProvider)
opentelemetry.attributes - Attribute validation and utility functions
opentelemetry.trace.propagation - Trace context propagation helpers (set/get span in context)

SDK:

opentelemetry.sdk._events - Events SDK implementation (EventLogger, EventLoggerProvider)
opentelemetry.sdk._logs.export - Log record export (BatchLogRecordProcessor, SimpleLogRecordProcessor, ConsoleLogExporter, InMemoryLogExporter)

Notes

The existing tox -e docs build has a pre-existing failure (Context cross-reference ambiguity in _logs._internal.LogRecord docstring) that is unrelated to this change and present on main
All new RST files follow the existing patterns used throughout docs/api/ and docs/sdk/
This is a partial fix for Some documentation not built into sphinx docs #2573. The issue also mentions automating RST generation, which could be a separate follow-up

Test plan

Ran tox -e docs locally; all new modules are picked up by sphinx-build (visible in the "reading sources" and "highlighting module code" output)
Verified the only build warnings are pre-existing (not introduced by this change)

linux-foundation-easycla · 2026-03-28T02:37:08Z

The committers listed above are authorized under a signed CLA.

✅ login: aabmass / name: Aaron Abbott (2ae9aac)
✅ login: lzchen / name: Leighton Chen (49ea551)
✅ login: MikeGoldsmith / name: Mike Goldsmith (1ea9519, 567fb46)
✅ login: raajheshkannaa / name: Raajhesh Kannaa Chidambaram (1453895, 1cfdc2d, 28f57f0, 2f86be6, 4145084, 4298f04, 68436f5, 8446ec1, 9ede05f, a98da60, c1aa745, c49473d, d0da97b, dd597f5, e63c9d9, fe998b0)

tammy-baylis-swi · 2026-03-30T16:52:57Z

Thanks @raajheshkannaa . Please could you sign the CLA as per contributing guidelines.

tammy-baylis-swi · 2026-04-02T00:18:15Z

Thanks! Next please run tox -e docs to fix some issues:

/home/runner/work/opentelemetry-python/opentelemetry-python/opentelemetry-sdk/src/opentelemetry/sdk/_events/__init__.py:docstring of opentelemetry.sdk._events.EventLogger.emit:1:py:class reference target not found: Event

raajheshkannaa · 2026-04-03T09:51:20Z

Rebased on main and ran tox -e docs. The Event reference was already covered by nitpick_ignore from the earlier commit, but the rebase surfaced a new unresolved reference for Token (from contextvars). Added that to nitpick_ignore as well. Docs build passes clean now.

tammy-baylis-swi · 2026-04-14T00:30:49Z

Thanks again @raajheshkannaa

I should have realized this earlier with my previous comment: the Events API is deprecated and users should use Logging API with event naming instead. This PR does make documentation consistent across the board, but the Events API docs render doesn't include the deprecation information (below screenshot).

What do other @open-telemetry/python-approvers think: include Events API in the docs index, or leave it out?

MikeGoldsmith

I feel we should leave out the events API. It's deprecated and we would not want someone to accidentally find / use it.

The other changes look good. Left a query and need to move the changelog entry.

raajheshkannaa · 2026-04-16T17:25:23Z

Thanks for the review, @MikeGoldsmith. Addressed in 4860bb3:

Removed the Events API additions (both docs/api/_events.rst and docs/sdk/_events.rst, plus the toctree entries and Event nitpick_ignore).
Moved the changelog entry up to Unreleased.
On get_finished_logs: the warning was coming from a :func: cross-reference in the InMemoryLogRecordExporter docstring, but get_finished_logs is a method. Fixed the docstring to :meth: and dropped the nitpick_ignore entry. Proper fix rather than suppression.

MikeGoldsmith

Thanks @raajheshkannaa 👍🏻

tammy-baylis-swi

Thank you! Maintainers will also review this.

raajheshkannaa · 2026-05-11T04:01:51Z

Pushed two follow-ups:

1453895 merges upstream/main so the public-symbols-check picks up Add registry keyword argument to PrometheusMetricReader #5055 (registry kwarg on PrometheusMetricReader) which was causing the unrelated 'Parameter was removed' breakage report.
a98da60 switches the AnyValue re-export to the PEP 484 'as AnyValue' form to satisfy ruff (the trailing noqa comment was pushing the line past the 79-char limit). pyright/mypy/ruff all treat 'from x import y as y' as an intentional re-export, so F401 stays clean without noqa.

raajheshkannaa · 2026-05-11T18:07:24Z

Pushed 9ede05f: switched the re-export to bare from opentelemetry.util.types import AnyValue plus an __all__ declaration. The previous as AnyValue form satisfied ruff but tripped pylint's C0414 (useless-import-alias). The __all__ pattern is what opentelemetry/util/_importlib_metadata.py uses and it satisfies both linters as an explicit re-export. Also re-merged main to pick up #5151. CI should be green now.

raajheshkannaa

Fair point. Pushed e63c9d9 which moves the workaround entirely into docs/conf.py:

import opentelemetry.attributes
from opentelemetry.util.types import AnyValue as _AnyValue
opentelemetry.attributes.AnyValue = _AnyValue

This injects AnyValue into the attributes module's namespace only during sphinx-build (where conf.py runs), so the forward reference resolves without changing the runtime public API. Reverted the from opentelemetry.util.types import AnyValue and __all__ from opentelemetry/attributes/__init__.py. Verified tox -e docs builds clean locally.

emdneto · 2026-05-12T22:35:33Z

Thanks for the PR!

Just a heads-up: we no longer update CHANGELOG.md directly. The changelog is now generated from changelog fragments using Towncrier.

Please add the appropriate changelog fragment for this change instead of editing CHANGELOG.md manually. You can find the instructions and expected format in CONTRIBUTING.md.

raajheshkannaa · 2026-05-14T00:01:41Z

Thanks @emdneto. Pushed 66b1f1e which migrates the changelog entry to a towncrier fragment:

Reverted my edit to CHANGELOG.md (now matches upstream/main verbatim after the merge of ci: introduce towncrier to generate changelog from fragments #5187).
Added .changelog/5017.fixed with the one-line description.

towncrier build --draft --version Unreleased renders correctly:

### Fixed

- Add missing `.rst` files to Sphinx documentation build for SDK logs,
  propagators, and exporter submodules.
  ([#5017](https://github.com/open-telemetry/opentelemetry-python/pull/5017))

Add RST files and toctree entries for modules that were not included in the sphinx doc build: API: - opentelemetry._events (Events API) - opentelemetry.attributes (Attributes utilities) - opentelemetry.trace.propagation (Trace context propagation) SDK: - opentelemetry.sdk._events (Events SDK implementation) - opentelemetry.sdk._logs.export (Log export processors and exporters) Closes open-telemetry#2573 Signed-off-by: Raajhesh Kannaa Chidambaram <[email protected]>

Signed-off-by: Raajhesh Kannaa Chidambaram <[email protected]>

Add CHANGELOG entry for the docs PR and suppress the Sphinx cross-reference warning for get_finished_logs (referenced as :func: in a docstring we did not modify).

…hangelog - Remove docs/api/_events.rst and docs/sdk/_events.rst (events API is deprecated per MikeGoldsmith, avoid exposing it in docs). - Remove _events entries from api/index.rst and sdk/index.rst toctrees. - Drop Event class nitpick_ignore entry (no longer needed). - Fix docstring cross-reference on InMemoryLogRecordExporter from :func: to :meth: since get_finished_logs is a method, and drop its nitpick_ignore entry. - Move changelog entry from 1.41.0/0.62b0 to Unreleased.

Submodule .rst files were removed in open-telemetry#5133. This was missed during the prior merge. Reviewed-by: Leighton Chen

…f resolution sphinx_autodoc_typehints calls get_type_hints on BoundedAttributes, which uses _ExtendedAttributes (Mapping[str, 'AnyValue']) from util.types. The forward ref to 'AnyValue' resolves in BoundedAttributes' __globals__ (the attributes module), not in util.types where it is defined. Re-export AnyValue into the attributes module namespace so the forward ref resolves and the docs build succeeds. Signed-off-by: Raajhesh Kannaa Chidambaram <[email protected]>

Signed-off-by: Raajhesh Kannaa Chidambaram <[email protected]>

…f re-exporting Signed-off-by: Raajhesh Kannaa Chidambaram <[email protected]>

@emdneto

Address @emdneto's feedback: replace direct CHANGELOG.md edit with a .changelog/5017.fixed fragment per the new towncrier workflow added in

… exist) The Submodules toctree referenced files that were never added in this PR and trace.propagation.rst was removed earlier per review. Sphinx -W treats the missing toctree target as a warning-as-error, breaking the docs build. Signed-off-by: Raajhesh Kannaa Chidambaram <[email protected]>

raajheshkannaa requested a review from a team as a code owner March 28, 2026 02:37

github-project-automation Bot added this to Python PR digest Mar 28, 2026

raajheshkannaa force-pushed the fix/sphinx-docs-build branch 2 times, most recently from 9ef33c3 to 20c26a9 Compare April 1, 2026 12:15

tammy-baylis-swi moved this to Reviewed PRs that need fixes in Python PR digest Apr 2, 2026

raajheshkannaa force-pushed the fix/sphinx-docs-build branch 2 times, most recently from 4b5e95f to 67c8e08 Compare April 3, 2026 09:51

raajheshkannaa force-pushed the fix/sphinx-docs-build branch from 67c8e08 to 7e3617d Compare April 3, 2026 14:04

xrmx moved this from Reviewed PRs that need fixes to Easy to review / merge / close in Python PR digest Apr 3, 2026

raajheshkannaa force-pushed the fix/sphinx-docs-build branch 2 times, most recently from 8587cf4 to d93aa2b Compare April 4, 2026 06:23

raajheshkannaa force-pushed the fix/sphinx-docs-build branch from d93aa2b to e641f48 Compare April 11, 2026 02:27

raajheshkannaa force-pushed the fix/sphinx-docs-build branch 2 times, most recently from cb4a049 to e523e0f Compare April 15, 2026 08:45

MikeGoldsmith requested changes Apr 16, 2026

View reviewed changes

Comment thread CHANGELOG.md Outdated

Comment thread docs/conf.py Outdated

github-project-automation Bot moved this from Easy to review / merge / close to Reviewed PRs that need fixes in Python PR digest Apr 16, 2026

raajheshkannaa force-pushed the fix/sphinx-docs-build branch from 4860bb3 to c48e463 Compare April 16, 2026 21:29

tammy-baylis-swi mentioned this pull request Apr 17, 2026

docs: add missing modules to Sphinx autodoc configuration #5108

Closed

6 tasks

MikeGoldsmith approved these changes Apr 17, 2026

View reviewed changes

tammy-baylis-swi approved these changes Apr 17, 2026

View reviewed changes

tammy-baylis-swi moved this from Reviewed PRs that need fixes to Approved PRs in Python PR digest Apr 17, 2026

raajheshkannaa force-pushed the fix/sphinx-docs-build branch 3 times, most recently from 3ececa6 to 247ceee Compare April 21, 2026 08:36

raajheshkannaa force-pushed the fix/sphinx-docs-build branch 2 times, most recently from e0020a8 to 28f57f0 Compare April 23, 2026 01:39

MukundaKatta mentioned this pull request Apr 26, 2026

Some documentation not built into sphinx docs #2573

Closed

lzchen reviewed May 7, 2026

View reviewed changes

Comment thread docs/api/trace.propagation.rst Outdated

raajheshkannaa commented May 12, 2026

View reviewed changes

raajheshkannaa added 11 commits May 17, 2026 18:42

fix: add Event class to nitpick_ignore for sphinx docs build

6f74d6c

Signed-off-by: Raajhesh Kannaa Chidambaram <[email protected]>

fix: add changelog entry and nitpick_ignore for get_finished_logs

099c26f

Add CHANGELOG entry for the docs PR and suppress the Sphinx cross-reference warning for get_finished_logs (referenced as :func: in a docstring we did not modify).

fix: add Token class to nitpick_ignore for sphinx docs build

742a03d

docs: remove trace.propagation.rst per maintainer review

1800292

Submodule .rst files were removed in open-telemetry#5133. This was missed during the prior merge. Reviewed-by: Leighton Chen

docs: use explicit re-export for AnyValue (fix ruff)

86b009a

Signed-off-by: Raajhesh Kannaa Chidambaram <[email protected]>

docs: use __all__ for AnyValue re-export to satisfy both pylint and ruff

c41b71f

docs: inject AnyValue into attributes namespace via conf.py instead o…

fb89f3c

…f re-exporting Signed-off-by: Raajhesh Kannaa Chidambaram <[email protected]>

docs: migrate changelog entry to towncrier fragment

bdca571

Address @emdneto's feedback: replace direct CHANGELOG.md edit with a .changelog/5017.fixed fragment per the new towncrier workflow added in

raajheshkannaa force-pushed the fix/sphinx-docs-build branch from 66b1f1e to bdca571 Compare May 17, 2026 22:45

lzchen and others added 4 commits May 18, 2026 11:44

Merge branch 'main' into fix/sphinx-docs-build

21fd79f

Merge remote-tracking branch 'upstream/main' into fix/sphinx-docs-build

f4b4807

Merge branch 'main' into fix/sphinx-docs-build

5d6d315

aabmass added this pull request to the merge queue May 20, 2026

Merged via the queue into open-telemetry:main with commit 7c4a6b8 May 20, 2026
480 checks passed

github-project-automation Bot moved this from Approved PRs to Done in Python PR digest May 20, 2026

Conversation

raajheshkannaa commented Mar 28, 2026

Summary

Modules added

Notes

Test plan

Uh oh!

linux-foundation-easycla Bot commented Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tammy-baylis-swi commented Mar 30, 2026

Uh oh!

tammy-baylis-swi commented Apr 2, 2026

Uh oh!

raajheshkannaa commented Apr 3, 2026

Uh oh!

tammy-baylis-swi commented Apr 14, 2026

Uh oh!

MikeGoldsmith left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

raajheshkannaa commented Apr 16, 2026

Uh oh!

MikeGoldsmith left a comment

Choose a reason for hiding this comment

Uh oh!

tammy-baylis-swi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

raajheshkannaa commented May 11, 2026

Uh oh!

raajheshkannaa commented May 11, 2026

Uh oh!

raajheshkannaa left a comment

Choose a reason for hiding this comment

Uh oh!

emdneto commented May 12, 2026

Uh oh!

raajheshkannaa commented May 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

linux-foundation-easycla Bot commented Mar 28, 2026 •

edited

Loading