Skip to content

docs: add missing modules to sphinx documentation build#5017

Open
raajheshkannaa wants to merge 4 commits intoopen-telemetry:mainfrom
raajheshkannaa:fix/sphinx-docs-build
Open

docs: add missing modules to sphinx documentation build#5017
raajheshkannaa wants to merge 4 commits intoopen-telemetry:mainfrom
raajheshkannaa:fix/sphinx-docs-build

Conversation

@raajheshkannaa
Copy link
Copy Markdown

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
Copy link
Copy Markdown

linux-foundation-easycla bot commented Mar 28, 2026

CLA Signed

The committers listed above are authorized under a signed CLA.

@tammy-baylis-swi
Copy link
Copy Markdown
Contributor

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

@raajheshkannaa 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
Copy link
Copy Markdown
Contributor

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

@tammy-baylis-swi tammy-baylis-swi moved this to Reviewed PRs that need fixes in Python PR digest Apr 2, 2026
@raajheshkannaa raajheshkannaa force-pushed the fix/sphinx-docs-build branch 2 times, most recently from 4b5e95f to 67c8e08 Compare April 3, 2026 09:51
@raajheshkannaa
Copy link
Copy Markdown
Author

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.

@raajheshkannaa raajheshkannaa force-pushed the fix/sphinx-docs-build branch from 67c8e08 to 7e3617d Compare April 3, 2026 14:04
@xrmx xrmx moved this from Reviewed PRs that need fixes to Easy to review / merge / close in Python PR digest Apr 3, 2026
@raajheshkannaa raajheshkannaa force-pushed the fix/sphinx-docs-build branch 2 times, most recently from 8587cf4 to d93aa2b Compare April 4, 2026 06:23
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 <495042+raajheshkannaa@users.noreply.github.com>
Signed-off-by: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com>
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).
@raajheshkannaa raajheshkannaa force-pushed the fix/sphinx-docs-build branch from d93aa2b to e641f48 Compare April 11, 2026 02:27
@tammy-baylis-swi
Copy link
Copy Markdown
Contributor

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?

events_doc

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Easy to review / merge / close

Development

Successfully merging this pull request may close these issues.

Some documentation not built into sphinx docs

3 participants