docs: Fix warning and treat them as errors (open-telemetry#666)

The CI is not able to catch many documentation problems because we are ignoring
warnings. This commit fixes most of the warnings, ignores the rest and enables
a flag to treat them as errors.

Co-authored-by: Diego Hurtado <[email protected]>

docs/conf.py

@@ -78,6 +78,8 @@
         None,
     ),
     "aiohttp": ("https://aiohttp.readthedocs.io/en/stable/", None),
+    "wrapt": ("https://wrapt.readthedocs.io/en/latest/", None),
+    "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
 }
 
 # http://www.sphinx-doc.org/en/master/config.html#confval-nitpicky
@@ -89,8 +91,22 @@
 nitpick_ignore = [
     ("py:class", "ValueT"),
     ("py:class", "MetricT"),
-    ("py:class", "typing.Tuple"),
-    ("py:class", "pymongo.monitoring.CommandListener"),
+    # Even if wrapt is added to intersphinx_mapping, sphinx keeps failing
+    # with "class reference target not found: ObjectProxy".
+    ("py:class", "ObjectProxy"),
+    # TODO: Understand why sphinx is not able to find this local class
+    (
+        "py:class",
+        "opentelemetry.trace.propagation.httptextformat.HTTPTextFormat",
+    ),
+    (
+        "any",
+        "opentelemetry.trace.propagation.httptextformat.HTTPTextFormat.extract",
+    ),
+    (
+        "any",
+        "opentelemetry.trace.propagation.httptextformat.HTTPTextFormat.inject",
+    ),
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/examples/django/README.rst

@@ -1,7 +1,7 @@
 OpenTelemetry Django Instrumentation Example
 ============================================
 
-This shows how to use `opentelemetry-ext-django` to automatically instrument a
+This shows how to use ``opentelemetry-ext-django`` to automatically instrument a
 Django app.
 
 For more user convenience, a Django app is already provided in this directory.
@@ -36,30 +36,30 @@ Execution of the Django app
 
 Set these environment variables first:
 
-#. `export OPENTELEMETRY_PYTHON_DJANGO_INSTRUMENT=True`
-#. `export DJANGO_SETTINGS_MODULE=instrumentation_example.settings`
+#. ``export OPENTELEMETRY_PYTHON_DJANGO_INSTRUMENT=True``
+#. ``export DJANGO_SETTINGS_MODULE=instrumentation_example.settings``
 
 The way to achieve OpenTelemetry instrumentation for your Django app is to use
-an `opentelemetry.ext.django.DjangoInstrumentor` to instrument the app.
+an ``opentelemetry.ext.django.DjangoInstrumentor`` to instrument the app.
 
-Clone the `opentelemetry-python` repository and go to `opentelemetry-python/docs/examples/django`.
+Clone the ``opentelemetry-python`` repository and go to ``opentelemetry-python/docs/examples/django``.
 
-Once there, open the `manage.py` file. The call to `DjangoInstrumentor().instrument()`
-in `main` is all that is needed to make the app be instrumented.
+Once there, open the ``manage.py`` file. The call to ``DjangoInstrumentor().instrument()``
+in ``main`` is all that is needed to make the app be instrumented.
 
-Run the Django app with `python manage.py runserver`.
+Run the Django app with ``python manage.py runserver``.
 
 Execution of the client
 .......................
 
 Open up a new console and activate the previous virtual environment there too:
 
-`source django_auto_instrumentation/bin/activate`
+``source django_auto_instrumentation/bin/activate``
 
-Go to `opentelemetry-python/ext/opentelemetry-ext-django/example`, once there
+Go to ``opentelemetry-python/ext/opentelemetry-ext-django/example``, once there
 run the client with:
 
-`python client.py hello`
+``python client.py hello``
 
 Go to the previous console, where the Django app is running. You should see
 output similar to this one:

docs/sdk/sdk.rst

@@ -6,6 +6,5 @@ OpenTelemetry Python SDK
 .. toctree::
     :maxdepth: 1
 
-    context
     metrics
     trace

ext/opentelemetry-ext-datadog/src/opentelemetry/ext/datadog/exporter.py

@@ -50,8 +50,8 @@ class DatadogSpanExporter(SpanExporter):
     """Datadog span exporter for OpenTelemetry.
 
     Args:
-        agent_url: The url of the Datadog Agent or use `DD_TRACE_AGENT_URL` environment variable
-        service: The service to be used for the application or use `DD_SERVICE` environment variable
+        agent_url: The url of the Datadog Agent or use ``DD_TRACE_AGENT_URL`` environment variable
+        service: The service to be used for the application or use ``DD_SERVICE`` environment variable
     """
 
     def __init__(self, agent_url=None, service=None):

ext/opentelemetry-ext-dbapi/src/opentelemetry/ext/dbapi/__init__.py

@@ -13,8 +13,9 @@
 # limitations under the License.
 
 """
-The trace integration with Database API supports libraries following the
-`Python Database API Specification v2.0. <https://www.python.org/dev/peps/pep-0249/>`_
+The trace integration with Database API supports libraries that follow the
+Python Database API Specification v2.0.
+`<https://www.python.org/dev/peps/pep-0249/>`_
 
 Usage
 -----
@@ -53,7 +54,7 @@
 
 
 def trace_integration(
-    connect_module: typing.Callable[..., any],
+    connect_module: typing.Callable[..., typing.Any],
     connect_method_name: str,
     database_component: str,
     database_type: str = "",
@@ -66,10 +67,13 @@ def trace_integration(
         Args:
             connect_module: Module name where connect method is available.
             connect_method_name: The connect method name.
-            database_component: Database driver name or database name "JDBI", "jdbc", "odbc", "postgreSQL".
+            database_component: Database driver name or database name "JDBI",
+                "jdbc", "odbc", "postgreSQL".
             database_type: The Database type. For any SQL database, "sql".
-            connection_attributes: Attribute names for database, port, host and user in Connection object.
-            tracer_provider: The :class:`TracerProvider` to use. If ommited the current configured one is used.
+            connection_attributes: Attribute names for database, port, host and
+                user in Connection object.
+            tracer_provider: The :class:`opentelemetry.trace.TracerProvider` to
+                use. If ommited the current configured one is used.
     """
     tracer = get_tracer(__name__, __version__, tracer_provider)
     wrap_connect(
@@ -84,7 +88,7 @@ def trace_integration(
 
 def wrap_connect(
     tracer: Tracer,
-    connect_module: typing.Callable[..., any],
+    connect_module: typing.Callable[..., typing.Any],
     connect_method_name: str,
     database_component: str,
     database_type: str = "",
@@ -94,20 +98,22 @@ def wrap_connect(
         https://www.python.org/dev/peps/pep-0249/
 
         Args:
-            tracer: The :class:`Tracer` to use.
+            tracer: The :class:`opentelemetry.trace.Tracer` to use.
             connect_module: Module name where connect method is available.
             connect_method_name: The connect method name.
-            database_component: Database driver name or database name "JDBI", "jdbc", "odbc", "postgreSQL".
+            database_component: Database driver name or database name "JDBI",
+                "jdbc", "odbc", "postgreSQL".
             database_type: The Database type. For any SQL database, "sql".
-            connection_attributes: Attribute names for database, port, host and user in Connection object.
+            connection_attributes: Attribute names for database, port, host and
+                user in Connection object.
     """
 
     # pylint: disable=unused-argument
-    def _wrap_connect(
-        wrapped: typing.Callable[..., any],
+    def wrap_connect_(
+        wrapped: typing.Callable[..., typing.Any],
         instance: typing.Any,
-        args: typing.Tuple[any, any],
-        kwargs: typing.Dict[any, any],
+        args: typing.Tuple[typing.Any, typing.Any],
+        kwargs: typing.Dict[typing.Any, typing.Any],
     ):
         db_integration = DatabaseApiIntegration(
             tracer,
@@ -119,14 +125,14 @@ def _wrap_connect(
 
     try:
         wrapt.wrap_function_wrapper(
-            connect_module, connect_method_name, _wrap_connect
+            connect_module, connect_method_name, wrap_connect_
         )
     except Exception as ex:  # pylint: disable=broad-except
         logger.warning("Failed to integrate with DB API. %s", str(ex))
 
 
 def unwrap_connect(
-    connect_module: typing.Callable[..., any], connect_method_name: str,
+    connect_module: typing.Callable[..., typing.Any], connect_method_name: str,
 ):
     """Disable integration with DB API library.
         https://www.python.org/dev/peps/pep-0249/
@@ -150,7 +156,7 @@ def instrument_connection(
     """Enable instrumentation in a database connection.
 
     Args:
-        tracer: The :class:`Tracer` to use.
+        tracer: The :class:`opentelemetry.trace.Tracer` to use.
         connection: The connection to instrument.
         database_component: Database driver name or database name "JDBI",
             "jdbc", "odbc", "postgreSQL".
@@ -213,9 +219,9 @@ def __init__(
 
     def wrapped_connection(
         self,
-        connect_method: typing.Callable[..., any],
-        args: typing.Tuple[any, any],
-        kwargs: typing.Dict[any, any],
+        connect_method: typing.Callable[..., typing.Any],
+        args: typing.Tuple[typing.Any, typing.Any],
+        kwargs: typing.Dict[typing.Any, typing.Any],
     ):
         """Add object proxy to connection object.
         """
@@ -279,9 +285,9 @@ def __init__(self, db_api_integration: DatabaseApiIntegration):
 
     def traced_execution(
         self,
-        query_method: typing.Callable[..., any],
-        *args: typing.Tuple[any, any],
-        **kwargs: typing.Dict[any, any]
+        query_method: typing.Callable[..., typing.Any],
+        *args: typing.Tuple[typing.Any, typing.Any],
+        **kwargs: typing.Dict[typing.Any, typing.Any]
     ):
 
         statement = args[0] if args else ""

ext/opentelemetry-ext-opentracing-shim/src/opentelemetry/ext/opentracing_shim/__init__.py

@@ -241,8 +241,7 @@ def set_tag(self, key, value):
     def log_kv(self, key_values, timestamp=None):
         """Implements the ``log_kv()`` method from the base class.
 
-        Logs an :class:`opentelemetry.trace.Event` for the wrapped
-        OpenTelemetry span.
+        Logs an event for the wrapped OpenTelemetry span.
 
         Note:
             The OpenTracing API defines the values of *key_values* to be of any

ext/opentelemetry-ext-prometheus/src/opentelemetry/ext/prometheus/__init__.py

@@ -94,7 +94,7 @@ class PrometheusMetricsExporter(MetricsExporter):
 
     Args:
         prefix: single-word application prefix relevant to the domain
-        the metric belongs to.
+            the metric belongs to.
     """
 
     def __init__(self, prefix: str = ""):

ext/opentelemetry-ext-sqlalchemy/src/opentelemetry/ext/sqlalchemy/__init__.py

@@ -16,11 +16,12 @@
 Instrument `sqlalchemy`_ to report SQL queries.
 
 There are two options for instrumenting code. The first option is to use
-the `opentelemetry-auto-instrumentation` executable which will automatically
+the ``opentelemetry-auto-instrumentation`` executable which will automatically
 instrument your SQLAlchemy engine. The second is to programmatically enable
 instrumentation via the following code:
 
 .. _sqlalchemy: https://pypi.org/project/sqlalchemy/
+
 Usage
 -----
 .. code:: python

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

@@ -29,7 +29,7 @@
 2. ``OPENTELEMETRY_PYTHON_SOMETHING_ELSE_``
 3. ``OPENTELEMETRY_PYTHON_SOMETHING_ELSE_AND__ELSE``
 4. ``OPENTELEMETRY_PYTHON_SOMETHING_ELSE_AND_else``
-4. ``OPENTELEMETRY_PYTHON_SOMETHING_ELSE_AND_else2``
+5. ``OPENTELEMETRY_PYTHON_SOMETHING_ELSE_AND_else2``
 
 These won't:
 

tox.ini

@@ -280,13 +280,13 @@ commands =
 
 [testenv:docs]
 deps =
-  -c dev-requirements.txt
-  -r docs-requirements.txt
+  -c {toxinidir}/dev-requirements.txt
+  -r {toxinidir}/docs-requirements.txt
 
 changedir = docs
 
 commands =
-  sphinx-build -E -a --keep-going -b html -T . _build/html
+  sphinx-build -E -a -W -b html -T . _build/html
 
 [testenv:py38-tracecontext]
 basepython: python3.8