Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 34a9616

Browse files
mauriciovasquezbernalocelotl
mauriciovasquezbernal
and
ocelotl
authored
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]>
1 parent 4ab3978 commit 34a9616

File tree

11 files changed

+68
-54
lines changed

11 files changed

+68
-54
lines changed

‎docs/conf.py

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,8 @@
7878
None,
7979
),
8080
"aiohttp": ("https://aiohttp.readthedocs.io/en/stable/", None),
81+
"wrapt": ("https://wrapt.readthedocs.io/en/latest/", None),
82+
"pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
8183
}
8284

8385
# http://www.sphinx-doc.org/en/master/config.html#confval-nitpicky
@@ -89,8 +91,22 @@
8991
nitpick_ignore = [
9092
("py:class", "ValueT"),
9193
("py:class", "MetricT"),
92-
("py:class", "typing.Tuple"),
93-
("py:class", "pymongo.monitoring.CommandListener"),
94+
# Even if wrapt is added to intersphinx_mapping, sphinx keeps failing
95+
# with "class reference target not found: ObjectProxy".
96+
("py:class", "ObjectProxy"),
97+
# TODO: Understand why sphinx is not able to find this local class
98+
(
99+
"py:class",
100+
"opentelemetry.trace.propagation.httptextformat.HTTPTextFormat",
101+
),
102+
(
103+
"any",
104+
"opentelemetry.trace.propagation.httptextformat.HTTPTextFormat.extract",
105+
),
106+
(
107+
"any",
108+
"opentelemetry.trace.propagation.httptextformat.HTTPTextFormat.inject",
109+
),
94110
]
95111

96112
# Add any paths that contain templates here, relative to this directory.

‎docs/examples/django/README.rst

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
OpenTelemetry Django Instrumentation Example
22
============================================
33

4-
This shows how to use `opentelemetry-ext-django` to automatically instrument a
4+
This shows how to use ``opentelemetry-ext-django`` to automatically instrument a
55
Django app.
66

77
For more user convenience, a Django app is already provided in this directory.
@@ -36,30 +36,30 @@ Execution of the Django app
3636

3737
Set these environment variables first:
3838

39-
#. `export OPENTELEMETRY_PYTHON_DJANGO_INSTRUMENT=True`
40-
#. `export DJANGO_SETTINGS_MODULE=instrumentation_example.settings`
39+
#. ``export OPENTELEMETRY_PYTHON_DJANGO_INSTRUMENT=True``
40+
#. ``export DJANGO_SETTINGS_MODULE=instrumentation_example.settings``
4141

4242
The way to achieve OpenTelemetry instrumentation for your Django app is to use
43-
an `opentelemetry.ext.django.DjangoInstrumentor` to instrument the app.
43+
an ``opentelemetry.ext.django.DjangoInstrumentor`` to instrument the app.
4444

45-
Clone the `opentelemetry-python` repository and go to `opentelemetry-python/docs/examples/django`.
45+
Clone the ``opentelemetry-python`` repository and go to ``opentelemetry-python/docs/examples/django``.
4646

47-
Once there, open the `manage.py` file. The call to `DjangoInstrumentor().instrument()`
48-
in `main` is all that is needed to make the app be instrumented.
47+
Once there, open the ``manage.py`` file. The call to ``DjangoInstrumentor().instrument()``
48+
in ``main`` is all that is needed to make the app be instrumented.
4949

50-
Run the Django app with `python manage.py runserver`.
50+
Run the Django app with ``python manage.py runserver``.
5151

5252
Execution of the client
5353
.......................
5454

5555
Open up a new console and activate the previous virtual environment there too:
5656

57-
`source django_auto_instrumentation/bin/activate`
57+
``source django_auto_instrumentation/bin/activate``
5858

59-
Go to `opentelemetry-python/ext/opentelemetry-ext-django/example`, once there
59+
Go to ``opentelemetry-python/ext/opentelemetry-ext-django/example``, once there
6060
run the client with:
6161

62-
`python client.py hello`
62+
``python client.py hello``
6363

6464
Go to the previous console, where the Django app is running. You should see
6565
output similar to this one:

‎docs/sdk/context.rst

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎docs/sdk/sdk.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,5 @@ OpenTelemetry Python SDK
66
.. toctree::
77
:maxdepth: 1
88

9-
context
109
metrics
1110
trace

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,8 @@ class DatadogSpanExporter(SpanExporter):
5050
"""Datadog span exporter for OpenTelemetry.
5151
5252
Args:
53-
agent_url: The url of the Datadog Agent or use `DD_TRACE_AGENT_URL` environment variable
54-
service: The service to be used for the application or use `DD_SERVICE` environment variable
53+
agent_url: The url of the Datadog Agent or use ``DD_TRACE_AGENT_URL`` environment variable
54+
service: The service to be used for the application or use ``DD_SERVICE`` environment variable
5555
"""
5656

5757
def __init__(self, agent_url=None, service=None):

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

Lines changed: 29 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,9 @@
1313
# limitations under the License.
1414

1515
"""
16-
The trace integration with Database API supports libraries following the
17-
`Python Database API Specification v2.0. <https://www.python.org/dev/peps/pep-0249/>`_
16+
The trace integration with Database API supports libraries that follow the
17+
Python Database API Specification v2.0.
18+
`<https://www.python.org/dev/peps/pep-0249/>`_
1819
1920
Usage
2021
-----
@@ -53,7 +54,7 @@
5354

5455

5556
def trace_integration(
56-
connect_module: typing.Callable[..., any],
57+
connect_module: typing.Callable[..., typing.Any],
5758
connect_method_name: str,
5859
database_component: str,
5960
database_type: str = "",
@@ -66,10 +67,13 @@ def trace_integration(
6667
Args:
6768
connect_module: Module name where connect method is available.
6869
connect_method_name: The connect method name.
69-
database_component: Database driver name or database name "JDBI", "jdbc", "odbc", "postgreSQL".
70+
database_component: Database driver name or database name "JDBI",
71+
"jdbc", "odbc", "postgreSQL".
7072
database_type: The Database type. For any SQL database, "sql".
71-
connection_attributes: Attribute names for database, port, host and user in Connection object.
72-
tracer_provider: The :class:`TracerProvider` to use. If ommited the current configured one is used.
73+
connection_attributes: Attribute names for database, port, host and
74+
user in Connection object.
75+
tracer_provider: The :class:`opentelemetry.trace.TracerProvider` to
76+
use. If ommited the current configured one is used.
7377
"""
7478
tracer = get_tracer(__name__, __version__, tracer_provider)
7579
wrap_connect(
@@ -84,7 +88,7 @@ def trace_integration(
8488

8589
def wrap_connect(
8690
tracer: Tracer,
87-
connect_module: typing.Callable[..., any],
91+
connect_module: typing.Callable[..., typing.Any],
8892
connect_method_name: str,
8993
database_component: str,
9094
database_type: str = "",
@@ -94,20 +98,22 @@ def wrap_connect(
9498
https://www.python.org/dev/peps/pep-0249/
9599
96100
Args:
97-
tracer: The :class:`Tracer` to use.
101+
tracer: The :class:`opentelemetry.trace.Tracer` to use.
98102
connect_module: Module name where connect method is available.
99103
connect_method_name: The connect method name.
100-
database_component: Database driver name or database name "JDBI", "jdbc", "odbc", "postgreSQL".
104+
database_component: Database driver name or database name "JDBI",
105+
"jdbc", "odbc", "postgreSQL".
101106
database_type: The Database type. For any SQL database, "sql".
102-
connection_attributes: Attribute names for database, port, host and user in Connection object.
107+
connection_attributes: Attribute names for database, port, host and
108+
user in Connection object.
103109
"""
104110

105111
# pylint: disable=unused-argument
106-
def _wrap_connect(
107-
wrapped: typing.Callable[..., any],
112+
def wrap_connect_(
113+
wrapped: typing.Callable[..., typing.Any],
108114
instance: typing.Any,
109-
args: typing.Tuple[any, any],
110-
kwargs: typing.Dict[any, any],
115+
args: typing.Tuple[typing.Any, typing.Any],
116+
kwargs: typing.Dict[typing.Any, typing.Any],
111117
):
112118
db_integration = DatabaseApiIntegration(
113119
tracer,
@@ -119,14 +125,14 @@ def _wrap_connect(
119125

120126
try:
121127
wrapt.wrap_function_wrapper(
122-
connect_module, connect_method_name, _wrap_connect
128+
connect_module, connect_method_name, wrap_connect_
123129
)
124130
except Exception as ex: # pylint: disable=broad-except
125131
logger.warning("Failed to integrate with DB API. %s", str(ex))
126132

127133

128134
def unwrap_connect(
129-
connect_module: typing.Callable[..., any], connect_method_name: str,
135+
connect_module: typing.Callable[..., typing.Any], connect_method_name: str,
130136
):
131137
"""Disable integration with DB API library.
132138
https://www.python.org/dev/peps/pep-0249/
@@ -150,7 +156,7 @@ def instrument_connection(
150156
"""Enable instrumentation in a database connection.
151157
152158
Args:
153-
tracer: The :class:`Tracer` to use.
159+
tracer: The :class:`opentelemetry.trace.Tracer` to use.
154160
connection: The connection to instrument.
155161
database_component: Database driver name or database name "JDBI",
156162
"jdbc", "odbc", "postgreSQL".
@@ -213,9 +219,9 @@ def __init__(
213219

214220
def wrapped_connection(
215221
self,
216-
connect_method: typing.Callable[..., any],
217-
args: typing.Tuple[any, any],
218-
kwargs: typing.Dict[any, any],
222+
connect_method: typing.Callable[..., typing.Any],
223+
args: typing.Tuple[typing.Any, typing.Any],
224+
kwargs: typing.Dict[typing.Any, typing.Any],
219225
):
220226
"""Add object proxy to connection object.
221227
"""
@@ -279,9 +285,9 @@ def __init__(self, db_api_integration: DatabaseApiIntegration):
279285

280286
def traced_execution(
281287
self,
282-
query_method: typing.Callable[..., any],
283-
*args: typing.Tuple[any, any],
284-
**kwargs: typing.Dict[any, any]
288+
query_method: typing.Callable[..., typing.Any],
289+
*args: typing.Tuple[typing.Any, typing.Any],
290+
**kwargs: typing.Dict[typing.Any, typing.Any]
285291
):
286292

287293
statement = args[0] if args else ""

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -241,8 +241,7 @@ def set_tag(self, key, value):
241241
def log_kv(self, key_values, timestamp=None):
242242
"""Implements the ``log_kv()`` method from the base class.
243243
244-
Logs an :class:`opentelemetry.trace.Event` for the wrapped
245-
OpenTelemetry span.
244+
Logs an event for the wrapped OpenTelemetry span.
246245
247246
Note:
248247
The OpenTracing API defines the values of *key_values* to be of any

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ class PrometheusMetricsExporter(MetricsExporter):
9494
9595
Args:
9696
prefix: single-word application prefix relevant to the domain
97-
the metric belongs to.
97+
the metric belongs to.
9898
"""
9999

100100
def __init__(self, prefix: str = ""):

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,12 @@
1616
Instrument `sqlalchemy`_ to report SQL queries.
1717
1818
There are two options for instrumenting code. The first option is to use
19-
the `opentelemetry-auto-instrumentation` executable which will automatically
19+
the ``opentelemetry-auto-instrumentation`` executable which will automatically
2020
instrument your SQLAlchemy engine. The second is to programmatically enable
2121
instrumentation via the following code:
2222
2323
.. _sqlalchemy: https://pypi.org/project/sqlalchemy/
24+
2425
Usage
2526
-----
2627
.. code:: python

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
2. ``OPENTELEMETRY_PYTHON_SOMETHING_ELSE_``
3030
3. ``OPENTELEMETRY_PYTHON_SOMETHING_ELSE_AND__ELSE``
3131
4. ``OPENTELEMETRY_PYTHON_SOMETHING_ELSE_AND_else``
32-
4. ``OPENTELEMETRY_PYTHON_SOMETHING_ELSE_AND_else2``
32+
5. ``OPENTELEMETRY_PYTHON_SOMETHING_ELSE_AND_else2``
3333
3434
These won't:
3535

‎tox.ini

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -280,13 +280,13 @@ commands =
280280

281281
[testenv:docs]
282282
deps =
283-
-c dev-requirements.txt
284-
-r docs-requirements.txt
283+
-c {toxinidir}/dev-requirements.txt
284+
-r {toxinidir}/docs-requirements.txt
285285

286286
changedir = docs
287287

288288
commands =
289-
sphinx-build -E -a --keep-going -b html -T . _build/html
289+
sphinx-build -E -a -W -b html -T . _build/html
290290

291291
[testenv:py38-tracecontext]
292292
basepython: python3.8

0 commit comments

Comments
 (0)