[docs] SDK documentation fixes (#2620)

Author: Alex Boten

docs/api/metrics.instrument.rst

@@ -5,4 +5,4 @@ opentelemetry._metrics.instrument
     :members:
     :private-members:
     :undoc-members:
-    :show-inheritance:
+    :no-show-inheritance:

docs/conf.py

@@ -142,12 +142,31 @@
     "examples/error_handler/error_handler_1",
 ]
 
+_exclude_members = [
+    "_ProxyObservableUpDownCounter",
+    "_ProxyHistogram",
+    "_ProxyObservableGauge",
+    "_ProxyInstrument",
+    "_ProxyAsynchronousInstrument",
+    "_ProxyCounter",
+    "_ProxyUpDownCounter",
+    "_ProxyObservableCounter",
+    "_ProxyObservableGauge",
+    "_abc_impl",
+    "_Adding",
+    "_Grouping",
+    "_Monotonic",
+    "_NonMonotonic",
+    "Synchronous",
+    "Asynchronous",
+]
+
 autodoc_default_options = {
     "members": True,
     "undoc-members": True,
     "show-inheritance": True,
     "member-order": "bysource",
-    "exclude-members": "_ProxyObservableUpDownCounter,_ProxyHistogram,_ProxyObservableGauge,_ProxyInstrument,_ProxyAsynchronousInstrument,_ProxyCounter,_ProxyUpDownCounter,_ProxyObservableCounter,_ProxyObservableGauge,_abc_impl",
+    "exclude-members": ",".join(_exclude_members),
 }
 
 # -- Options for HTML output -------------------------------------------------

docs/sdk/metrics.export.rst

@@ -0,0 +1,7 @@
+opentelemetry.sdk._metrics.export
+=================================
+
+.. automodule:: opentelemetry.sdk._metrics.export
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/sdk/metrics.point.rst

@@ -0,0 +1,7 @@
+opentelemetry.sdk._metrics.point
+================================
+
+.. automodule:: opentelemetry.sdk._metrics.point
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/sdk/metrics.rst

@@ -16,6 +16,8 @@ Submodules
    metrics.view
    metrics.aggregation
    metrics.metric_reader
+   metrics.point
+   metrics.export
 
 .. automodule:: opentelemetry.sdk._metrics
     :members:

opentelemetry-api/src/opentelemetry/_metrics/__init__.py

@@ -331,7 +331,7 @@ def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Observat
 
     @abstractmethod
     def create_histogram(self, name, unit="", description="") -> Histogram:
-        """Creates a `Histogram` instrument
+        """Creates a `opentelemetry._metrics.instrument.Histogram` instrument
 
         Args:
             name: The name of the instrument to be created

opentelemetry-api/src/opentelemetry/_metrics/instrument.py

@@ -43,6 +43,8 @@
 
 
 class Instrument(ABC):
+    """Abstract class that serves as base for all instruments."""
+
     @abstractmethod
     def __init__(self, name, unit="", description=""):
         pass
@@ -120,6 +122,8 @@ def add(self, amount, attributes=None):
 
 
 class NoOpCounter(Counter):
+    """No-op implementation of `Counter`."""
+
     def __init__(self, name, unit="", description=""):
         super().__init__(name, unit=unit, description=description)
 
@@ -145,6 +149,8 @@ def add(self, amount, attributes=None):
 
 
 class NoOpUpDownCounter(UpDownCounter):
+    """No-op implementation of `UpDownCounter`."""
+
     def __init__(self, name, unit="", description=""):
         super().__init__(name, unit=unit, description=description)
 
@@ -170,6 +176,8 @@ class ObservableCounter(_Monotonic, Asynchronous):
 
 
 class NoOpObservableCounter(ObservableCounter):
+    """No-op implementation of `ObservableCounter`."""
+
     def __init__(self, name, callbacks=None, unit="", description=""):
         super().__init__(name, callbacks, unit=unit, description=description)
 
@@ -193,6 +201,8 @@ class ObservableUpDownCounter(_NonMonotonic, Asynchronous):
 
 
 class NoOpObservableUpDownCounter(ObservableUpDownCounter):
+    """No-op implementation of `ObservableUpDownCounter`."""
+
     def __init__(self, name, callbacks=None, unit="", description=""):
         super().__init__(name, callbacks, unit=unit, description=description)
 
@@ -221,6 +231,8 @@ def record(self, amount, attributes=None):
 
 
 class NoOpHistogram(Histogram):
+    """No-op implementation of `Histogram`."""
+
     def __init__(self, name, unit="", description=""):
         super().__init__(name, unit=unit, description=description)
 
@@ -247,6 +259,8 @@ class ObservableGauge(_Grouping, Asynchronous):
 
 
 class NoOpObservableGauge(ObservableGauge):
+    """No-op implementation of `ObservableGauge`."""
+
     def __init__(self, name, callbacks=None, unit="", description=""):
         super().__init__(name, callbacks, unit=unit, description=description)
 

opentelemetry-sdk/src/opentelemetry/sdk/_metrics/aggregation.py

@@ -82,16 +82,16 @@ class DefaultAggregation(_AggregationFactory):
     This aggregation will create an actual aggregation depending on the
     instrument type, as specified next:
 
-    ========================= ====================================
-    Instrument                Aggregation
-    ========================= ====================================
-    `Counter`                 `SumAggregation`
-    `UpDownCounter`           `SumAggregation`
-    `ObservableCounter`       `SumAggregation`
-    `ObservableUpDownCounter` `SumAggregation`
-    `Histogram`               `ExplicitBucketHistogramAggregation`
-    `ObservableGauge`         `LastValueAggregation`
-    ========================= ====================================
+    ============================================= ====================================
+    Instrument                                    Aggregation
+    ============================================= ====================================
+    `Counter`                                     `SumAggregation`
+    `UpDownCounter`                               `SumAggregation`
+    `ObservableCounter`                           `SumAggregation`
+    `ObservableUpDownCounter`                     `SumAggregation`
+    `opentelemetry._metrics.instrument.Histogram` `ExplicitBucketHistogramAggregation`
+    `ObservableGauge`                             `LastValueAggregation`
+    ============================================= ====================================
     """
 
     def _create_aggregation(self, instrument: Instrument) -> _Aggregation:

opentelemetry-sdk/src/opentelemetry/sdk/_metrics/export/__init__.py

@@ -55,7 +55,7 @@ def export(self, metrics: Sequence[Metric]) -> "MetricExportResult":
         """Exports a batch of telemetry data.
 
         Args:
-            metrics: The list of `opentelemetry.sdk._metrics.data.MetricData` objects to be exported
+            metrics: The list of `opentelemetry.sdk._metrics.point.Metric` objects to be exported
 
         Returns:
             The result of the export
@@ -97,7 +97,7 @@ def shutdown(self) -> None:
 
 
 class InMemoryMetricReader(MetricReader):
-    """Implementation of :class:`MetricReader` that returns its metrics from :func:`metrics`.
+    """Implementation of `MetricReader` that returns its metrics from :func:`get_metrics`.
 
     This is useful for e.g. unit tests.
     """