From a2a68ea3c6600b00f013c02048b5dbfba7eee559 Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Fri, 27 Mar 2026 22:36:46 -0400 Subject: [PATCH 01/12] docs: add missing modules to sphinx documentation build 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 #2573 Signed-off-by: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> --- docs/api/_events.rst | 10 ++++++++++ docs/api/attributes.rst | 7 +++++++ docs/api/index.rst | 2 ++ docs/api/trace.propagation.rst | 7 +++++++ docs/api/trace.rst | 9 +++++++++ docs/sdk/_events.rst | 7 +++++++ docs/sdk/_logs.export.rst | 7 +++++++ docs/sdk/_logs.rst | 10 ++++++++++ docs/sdk/index.rst | 1 + 9 files changed, 60 insertions(+) create mode 100644 docs/api/_events.rst create mode 100644 docs/api/attributes.rst create mode 100644 docs/api/trace.propagation.rst create mode 100644 docs/sdk/_events.rst create mode 100644 docs/sdk/_logs.export.rst diff --git a/docs/api/_events.rst b/docs/api/_events.rst new file mode 100644 index 00000000000..1b56e215a21 --- /dev/null +++ b/docs/api/_events.rst @@ -0,0 +1,10 @@ +opentelemetry._events package +============================= + +Module contents +--------------- + +.. automodule:: opentelemetry._events + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/attributes.rst b/docs/api/attributes.rst new file mode 100644 index 00000000000..4ae7104f665 --- /dev/null +++ b/docs/api/attributes.rst @@ -0,0 +1,7 @@ +opentelemetry.attributes +======================== + +.. automodule:: opentelemetry.attributes + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/index.rst b/docs/api/index.rst index 72e3ba2a074..59da3a32337 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -14,7 +14,9 @@ For the concrete implementation of these interfaces, see the .. toctree:: :maxdepth: 1 + _events _logs + attributes baggage context propagate diff --git a/docs/api/trace.propagation.rst b/docs/api/trace.propagation.rst new file mode 100644 index 00000000000..1b63d758066 --- /dev/null +++ b/docs/api/trace.propagation.rst @@ -0,0 +1,7 @@ +opentelemetry.trace.propagation +=============================== + +.. automodule:: opentelemetry.trace.propagation + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/trace.rst b/docs/api/trace.rst index b59d9dce6f8..bed009f3372 100644 --- a/docs/api/trace.rst +++ b/docs/api/trace.rst @@ -1,6 +1,15 @@ opentelemetry.trace package =========================== +Submodules +---------- + +.. toctree:: + + trace.status + trace.span + trace.propagation + Module contents --------------- diff --git a/docs/sdk/_events.rst b/docs/sdk/_events.rst new file mode 100644 index 00000000000..1485f3fea9f --- /dev/null +++ b/docs/sdk/_events.rst @@ -0,0 +1,7 @@ +opentelemetry.sdk._events package +================================= + +.. automodule:: opentelemetry.sdk._events + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sdk/_logs.export.rst b/docs/sdk/_logs.export.rst new file mode 100644 index 00000000000..19a40237424 --- /dev/null +++ b/docs/sdk/_logs.export.rst @@ -0,0 +1,7 @@ +opentelemetry.sdk._logs.export +============================== + +.. automodule:: opentelemetry.sdk._logs.export + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sdk/_logs.rst b/docs/sdk/_logs.rst index 185e7006e40..fb69caeda79 100644 --- a/docs/sdk/_logs.rst +++ b/docs/sdk/_logs.rst @@ -1,6 +1,16 @@ opentelemetry.sdk._logs package =============================== +Submodules +---------- + +.. toctree:: + + _logs.export + +Module contents +--------------- + .. automodule:: opentelemetry.sdk._logs :members: :undoc-members: diff --git a/docs/sdk/index.rst b/docs/sdk/index.rst index ecc4a390856..80925f76564 100644 --- a/docs/sdk/index.rst +++ b/docs/sdk/index.rst @@ -14,6 +14,7 @@ processed, and exported. .. toctree:: :maxdepth: 1 + _events _logs resources trace From 6f74d6cfa775bef3b38e9d42847a954bb90b4fb6 Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Thu, 2 Apr 2026 09:02:30 -0400 Subject: [PATCH 02/12] fix: add Event class to nitpick_ignore for sphinx docs build Signed-off-by: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> --- docs/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 45fc14df0cf..fb6d48c060e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -181,6 +181,10 @@ "py:class", "_ExtendedAttributes", ), + ( + "py:class", + "Event", + ), ] # Add any paths that contain templates here, relative to this directory. From 099c26fe6ace97235b9b03ca95bf4f4966bc01f9 Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Thu, 2 Apr 2026 21:36:31 -0400 Subject: [PATCH 03/12] fix: add changelog entry and nitpick_ignore for get_finished_logs 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). --- CHANGELOG.md | 2 ++ docs/conf.py | 1 + 2 files changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7501f2a0450..a7255a92206 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,6 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ([#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 + ([#5017](https://github.com/open-telemetry/opentelemetry-python/pull/5017)) - `opentelemetry-sdk`: Add `process` resource detector support to declarative file configuration via `detection_development.detectors[].process` ([#5001](https://github.com/open-telemetry/opentelemetry-python/pull/5001)) - `opentelemetry-sdk`: Add shared `_parse_headers` helper for declarative config OTLP exporters diff --git a/docs/conf.py b/docs/conf.py index fb6d48c060e..96f4fc0eb22 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -185,6 +185,7 @@ "py:class", "Event", ), + ("py:func", "get_finished_logs"), ] # Add any paths that contain templates here, relative to this directory. From 742a03d02d80519635fdece5d913ba6c3695584e Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Fri, 3 Apr 2026 05:51:05 -0400 Subject: [PATCH 04/12] fix: add Token class to nitpick_ignore for sphinx docs build --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index 96f4fc0eb22..e7a2faad2e4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -186,6 +186,7 @@ "Event", ), ("py:func", "get_finished_logs"), + ("py:class", "Token"), ] # Add any paths that contain templates here, relative to this directory. From 4a8a87297c4db3e96d673bf343eec1be53b36b7b Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Thu, 16 Apr 2026 13:25:10 -0400 Subject: [PATCH 05/12] address review: remove events API, fix get_finished_logs xref, move changelog - 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. --- CHANGELOG.md | 2 -- docs/api/_events.rst | 10 ---------- docs/api/index.rst | 1 - docs/conf.py | 5 ----- docs/sdk/_events.rst | 7 ------- docs/sdk/index.rst | 1 - .../_logs/_internal/export/in_memory_log_exporter.py | 2 +- 7 files changed, 1 insertion(+), 27 deletions(-) delete mode 100644 docs/api/_events.rst delete mode 100644 docs/sdk/_events.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index a7255a92206..7501f2a0450 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,8 +35,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ([#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 - ([#5017](https://github.com/open-telemetry/opentelemetry-python/pull/5017)) - `opentelemetry-sdk`: Add `process` resource detector support to declarative file configuration via `detection_development.detectors[].process` ([#5001](https://github.com/open-telemetry/opentelemetry-python/pull/5001)) - `opentelemetry-sdk`: Add shared `_parse_headers` helper for declarative config OTLP exporters diff --git a/docs/api/_events.rst b/docs/api/_events.rst deleted file mode 100644 index 1b56e215a21..00000000000 --- a/docs/api/_events.rst +++ /dev/null @@ -1,10 +0,0 @@ -opentelemetry._events package -============================= - -Module contents ---------------- - -.. automodule:: opentelemetry._events - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/api/index.rst b/docs/api/index.rst index 59da3a32337..13a6cb1e9c8 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -14,7 +14,6 @@ For the concrete implementation of these interfaces, see the .. toctree:: :maxdepth: 1 - _events _logs attributes baggage diff --git a/docs/conf.py b/docs/conf.py index e7a2faad2e4..5e373bddb8c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -181,11 +181,6 @@ "py:class", "_ExtendedAttributes", ), - ( - "py:class", - "Event", - ), - ("py:func", "get_finished_logs"), ("py:class", "Token"), ] diff --git a/docs/sdk/_events.rst b/docs/sdk/_events.rst deleted file mode 100644 index 1485f3fea9f..00000000000 --- a/docs/sdk/_events.rst +++ /dev/null @@ -1,7 +0,0 @@ -opentelemetry.sdk._events package -================================= - -.. automodule:: opentelemetry.sdk._events - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/sdk/index.rst b/docs/sdk/index.rst index 80925f76564..ecc4a390856 100644 --- a/docs/sdk/index.rst +++ b/docs/sdk/index.rst @@ -14,7 +14,6 @@ processed, and exported. .. toctree:: :maxdepth: 1 - _events _logs resources trace diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/_logs/_internal/export/in_memory_log_exporter.py b/opentelemetry-sdk/src/opentelemetry/sdk/_logs/_internal/export/in_memory_log_exporter.py index 5a6a0495bd8..1f793745458 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/_logs/_internal/export/in_memory_log_exporter.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/_logs/_internal/export/in_memory_log_exporter.py @@ -18,7 +18,7 @@ class InMemoryLogRecordExporter(LogRecordExporter): This class can be used for testing purposes. It stores the exported logs in a list in memory that can be retrieved using the - :func:`.get_finished_logs` method. + :meth:`.get_finished_logs` method. """ def __init__(self): From 1800292e1cbfaa00be9debd90b9e854a53522b96 Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Fri, 8 May 2026 01:08:18 -0400 Subject: [PATCH 06/12] docs: remove trace.propagation.rst per maintainer review Submodule .rst files were removed in #5133. This was missed during the prior merge. Reviewed-by: Leighton Chen --- docs/api/trace.propagation.rst | 7 ------- 1 file changed, 7 deletions(-) delete mode 100644 docs/api/trace.propagation.rst diff --git a/docs/api/trace.propagation.rst b/docs/api/trace.propagation.rst deleted file mode 100644 index 1b63d758066..00000000000 --- a/docs/api/trace.propagation.rst +++ /dev/null @@ -1,7 +0,0 @@ -opentelemetry.trace.propagation -=============================== - -.. automodule:: opentelemetry.trace.propagation - :members: - :undoc-members: - :show-inheritance: From 20eb019265e8fe8d63ca59ce64cc5cd0106191ca Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Fri, 8 May 2026 18:17:24 -0400 Subject: [PATCH 07/12] docs: re-export AnyValue from attributes module for sphinx forward-ref 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 <495042+raajheshkannaa@users.noreply.github.com> --- opentelemetry-api/src/opentelemetry/attributes/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/opentelemetry-api/src/opentelemetry/attributes/__init__.py b/opentelemetry-api/src/opentelemetry/attributes/__init__.py index 09d01d3411a..722af4e6981 100644 --- a/opentelemetry-api/src/opentelemetry/attributes/__init__.py +++ b/opentelemetry-api/src/opentelemetry/attributes/__init__.py @@ -8,6 +8,7 @@ from collections.abc import Mapping, MutableMapping, Sequence from opentelemetry.util import types +from opentelemetry.util.types import AnyValue # noqa: F401 # exposes AnyValue for forward-ref resolution by sphinx_autodoc_typehints # bytes are accepted as a user supplied value for attributes but # decoded to strings internally. From 86b009a45ded914669917c84d445613251862909 Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Mon, 11 May 2026 00:01:40 -0400 Subject: [PATCH 08/12] docs: use explicit re-export for AnyValue (fix ruff) Signed-off-by: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> --- opentelemetry-api/src/opentelemetry/attributes/__init__.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/opentelemetry-api/src/opentelemetry/attributes/__init__.py b/opentelemetry-api/src/opentelemetry/attributes/__init__.py index 722af4e6981..a2776b36bd4 100644 --- a/opentelemetry-api/src/opentelemetry/attributes/__init__.py +++ b/opentelemetry-api/src/opentelemetry/attributes/__init__.py @@ -8,7 +8,11 @@ from collections.abc import Mapping, MutableMapping, Sequence from opentelemetry.util import types -from opentelemetry.util.types import AnyValue # noqa: F401 # exposes AnyValue for forward-ref resolution by sphinx_autodoc_typehints + +# Re-exported so the "AnyValue" forward reference in +# util.types._ExtendedAttributes resolves against this module's globals when +# sphinx_autodoc_typehints introspects BoundedAttributes. +from opentelemetry.util.types import AnyValue as AnyValue # bytes are accepted as a user supplied value for attributes but # decoded to strings internally. From c41b71f0e5197499b20130906c49bfbc70a03c3f Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Mon, 11 May 2026 14:07:12 -0400 Subject: [PATCH 09/12] docs: use __all__ for AnyValue re-export to satisfy both pylint and ruff --- opentelemetry-api/src/opentelemetry/attributes/__init__.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/opentelemetry-api/src/opentelemetry/attributes/__init__.py b/opentelemetry-api/src/opentelemetry/attributes/__init__.py index a2776b36bd4..b50a537c259 100644 --- a/opentelemetry-api/src/opentelemetry/attributes/__init__.py +++ b/opentelemetry-api/src/opentelemetry/attributes/__init__.py @@ -12,7 +12,9 @@ # Re-exported so the "AnyValue" forward reference in # util.types._ExtendedAttributes resolves against this module's globals when # sphinx_autodoc_typehints introspects BoundedAttributes. -from opentelemetry.util.types import AnyValue as AnyValue +from opentelemetry.util.types import AnyValue + +__all__ = ["AnyValue", "BoundedAttributes"] # bytes are accepted as a user supplied value for attributes but # decoded to strings internally. From fb89f3cd9dba11169bcacec2f508d8bc3ac7a9fb Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Mon, 11 May 2026 22:04:28 -0400 Subject: [PATCH 10/12] docs: inject AnyValue into attributes namespace via conf.py instead of re-exporting Signed-off-by: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> --- docs/conf.py | 9 +++++++++ .../src/opentelemetry/attributes/__init__.py | 7 ------- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5e373bddb8c..66112b465a8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -26,6 +26,15 @@ settings.configure() +# Provide AnyValue in opentelemetry.attributes module's namespace so the +# "AnyValue" forward reference in opentelemetry.util.types._ExtendedAttributes +# resolves when sphinx_autodoc_typehints calls typing.get_type_hints() on +# BoundedAttributes (whose __globals__ is the attributes module). Docs-only. +import opentelemetry.attributes # noqa: E402 +from opentelemetry.util.types import AnyValue as _AnyValue # noqa: E402 + +opentelemetry.attributes.AnyValue = _AnyValue + source_dirs = [ os.path.abspath("../opentelemetry-instrumentation/src/"), diff --git a/opentelemetry-api/src/opentelemetry/attributes/__init__.py b/opentelemetry-api/src/opentelemetry/attributes/__init__.py index b50a537c259..09d01d3411a 100644 --- a/opentelemetry-api/src/opentelemetry/attributes/__init__.py +++ b/opentelemetry-api/src/opentelemetry/attributes/__init__.py @@ -9,13 +9,6 @@ from opentelemetry.util import types -# Re-exported so the "AnyValue" forward reference in -# util.types._ExtendedAttributes resolves against this module's globals when -# sphinx_autodoc_typehints introspects BoundedAttributes. -from opentelemetry.util.types import AnyValue - -__all__ = ["AnyValue", "BoundedAttributes"] - # bytes are accepted as a user supplied value for attributes but # decoded to strings internally. _VALID_ATTR_VALUE_TYPES = (bool, str, bytes, int, float) From bdca571eb5e8e970088bfeae3aec59fae170c9aa Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Wed, 13 May 2026 20:01:34 -0400 Subject: [PATCH 11/12] docs: migrate changelog entry to towncrier fragment Address @emdneto's feedback: replace direct CHANGELOG.md edit with a .changelog/5017.fixed fragment per the new towncrier workflow added in --- .changelog/5017.fixed | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 .changelog/5017.fixed diff --git a/.changelog/5017.fixed b/.changelog/5017.fixed new file mode 100644 index 00000000000..3df11b23f3e --- /dev/null +++ b/.changelog/5017.fixed @@ -0,0 +1,2 @@ +Add missing `.rst` files to Sphinx documentation build for SDK logs, +propagators, and exporter submodules. From 54dbfc58de4533225c91fea60ccf0a3071ebaeaa Mon Sep 17 00:00:00 2001 From: Raajhesh Kannaa Chidambaram <495042+raajheshkannaa@users.noreply.github.com> Date: Tue, 19 May 2026 11:18:08 -0400 Subject: [PATCH 12/12] docs: drop dead trace toctree (no trace.{status,span,propagation}.rst 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 <495042+raajheshkannaa@users.noreply.github.com> --- docs/api/trace.rst | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/api/trace.rst b/docs/api/trace.rst index bed009f3372..b59d9dce6f8 100644 --- a/docs/api/trace.rst +++ b/docs/api/trace.rst @@ -1,15 +1,6 @@ opentelemetry.trace package =========================== -Submodules ----------- - -.. toctree:: - - trace.status - trace.span - trace.propagation - Module contents ---------------