Skip to content

docs: add missing modules to sphinx documentation build#5017

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

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

Conversation

@raajheshkannaa
Copy link
Copy Markdown

@raajheshkannaa raajheshkannaa commented Mar 28, 2026

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)

@raajheshkannaa raajheshkannaa requested a review from a team as a code owner March 28, 2026 02:37
@linux-foundation-easycla
Copy link
Copy Markdown

linux-foundation-easycla bot commented Mar 28, 2026 •
edited
Loading

CLA Signed

The committers listed above are authorized under a signed CLA.

@tammy-baylis-swi
Copy link
Copy Markdown
Contributor

tammy-baylis-swi commented Mar 30, 2026

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

tammy-baylis-swi commented Apr 2, 2026

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

raajheshkannaa commented Apr 3, 2026

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
@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

tammy-baylis-swi commented Apr 14, 2026

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

@raajheshkannaa raajheshkannaa force-pushed the fix/sphinx-docs-build branch 2 times, most recently from cb4a049 to e523e0f Compare April 15, 2026 08:45
MikeGoldsmith
MikeGoldsmith requested changes Apr 16, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@MikeGoldsmith MikeGoldsmith left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread CHANGELOG.md Outdated
([#5034](https://github.com/open-telemetry/opentelemetry-python/pull/5034))
- Fix `BatchLogRecordProcessor` default `schedule_delay_millis` from 5000ms to 1000ms to comply with the OTel specification. Note: logs may be exported 5x more frequently by default (e.g. for users who don't explicitly set the `OTEL_BLRP_SCHEDULE_DELAY` env var).
([#4998](https://github.com/open-telemetry/opentelemetry-python/pull/4998))
- Add missing .rst files to Sphinx documentation build for SDK logs, propagators, and exporter submodules
Copy link
Copy Markdown
Member

@MikeGoldsmith MikeGoldsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please move this up into Unreleased.

Comment thread docs/conf.py Outdated
"py:class",
"Event",
),
("py:func", "get_finished_logs"),
Copy link
Copy Markdown
Member

@MikeGoldsmith MikeGoldsmith Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are we suppressing get_finished_logs here?

@github-project-automation 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
Copy link
Copy Markdown
Author

raajheshkannaa commented Apr 16, 2026

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.

@raajheshkannaa
docs: add missing modules to sphinx documentation build
dbb0504 
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>
@raajheshkannaa
fix: add Event class to nitpick_ignore for sphinx docs build
3fdd5cc 
Signed-off-by: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com>
@raajheshkannaa
fix: add changelog entry and nitpick_ignore for get_finished_logs
359a544 
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
fix: add Token class to nitpick_ignore for sphinx docs build
2f1d621
@raajheshkannaa
address review: remove events API, fix get_finished_logs xref, move c…
c48e463 
…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.
@raajheshkannaa raajheshkannaa force-pushed the fix/sphinx-docs-build branch from 4860bb3 to c48e463 Compare April 16, 2026 21:29
@tammy-baylis-swi tammy-baylis-swi mentioned this pull request Apr 17, 2026
Closed
6 tasks
MikeGoldsmith
MikeGoldsmith approved these changes Apr 17, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@MikeGoldsmith MikeGoldsmith left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @raajheshkannaa 👍🏻

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

Reviewers

@MikeGoldsmith MikeGoldsmith MikeGoldsmith approved these changes

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

Python PR digest
Status: Reviewed PRs that need fixes

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Some documentation not built into sphinx docs

4 participants

@raajheshkannaa @tammy-baylis-swi @MikeGoldsmith @xrmx