Add rstcheck in pre-commit (#3777)

* Fix a bunch of rstcheck warnings

* Add rstcheck to pre-commit

* Ignore automodule

* Update changelog and contributing

* tox -e ruff -> tox -e precommit

But keep the old name for compat

.github/workflows/misc_0.yml

@@ -157,8 +157,8 @@ jobs:
       - name: Run tests
         run: tox -e shellcheck
 
-  ruff:
-    name: ruff
+  precommit:
+    name: precommit
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
@@ -174,7 +174,7 @@ jobs:
         run: pip install tox-uv
 
       - name: Run tests
-        run: tox -e ruff
+        run: tox -e precommit
 
   typecheck:
     name: typecheck

.pre-commit-config.yaml

@@ -13,3 +13,9 @@ repos:
     rev: 0.6.0
     hooks:
       - id: uv-lock
+  - repo: https://github.com/rstcheck/rstcheck
+    rev: 77490ffa33bfc0928975ae3cf904219903db755d # frozen: v6.2.5
+    hooks:
+      - id: rstcheck
+        additional_dependencies: ['rstcheck[sphinx]']
+        args: ["--report-level", "warning"]

.rstcheck.cfg

@@ -0,0 +1,2 @@
+[rstcheck]
+ignore_directives = automodule

CHANGELOG.md

@@ -16,6 +16,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - `opentelemetry-instrumentation`: botocore: Add support for AWS Secrets Manager semantic convention attribute
   ([#3765](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3765))
+- Add `rstcheck` to pre-commit to stop introducing invalid RST
+  ([#3777](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3777))
+
 
 ## Version 1.37.0/0.58b0 (2025-09-11)
 

CONTRIBUTING.md

@@ -84,8 +84,9 @@ You can run `tox` with the following arguments:
 * `tox -e lint-some-package` to run lint checks on `some-package`
 * `tox -e generate-workflows` to run creation of new CI workflows if tox environments have been updated
 * `tox -e ruff` to run ruff linter and formatter checks against the entire codebase
+* `tox -e precommit` to run all `pre-commit` actions
 
-`ruff check` and `ruff format` are executed when `tox -e ruff` is run. We strongly recommend you to configure [pre-commit](https://pre-commit.com/) locally to run `ruff` automatically before each commit by installing it as git hooks. You just need to [install pre-commit](https://pre-commit.com/#install) in your environment:
+`ruff check` and `ruff format` are executed when `tox -e ruff` is run. We strongly recommend you to configure [pre-commit](https://pre-commit.com/) locally to run `ruff` and `rstcheck` automatically before each commit by installing it as git hooks. You just need to [install pre-commit](https://pre-commit.com/#install) in your environment:
 
 ```console
 pip install pre-commit -c dev-requirements.txt

_template/README.rst

@@ -1,5 +1,5 @@
 OpenTelemetry <REPLACE ME> Instrumentation
-===========================
+==========================================
 
 |pypi|
 
@@ -20,5 +20,5 @@ Installation
 References
 ----------
 
-* `OpenTelemetry <REPLACE ME>/ Tracing <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/<REPLACE ME>/<REPLACE ME>.html>`_
+* `OpenTelemetry REPLACE ME/ Tracing <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/REPLACE ME/REPLACE ME.html>`_
 * `OpenTelemetry Project <https://opentelemetry.io/>`_

instrumentation-genai/opentelemetry-instrumentation-google-genai/examples/manual/README.rst

@@ -1,5 +1,5 @@
 OpenTelemetry Google GenAI SDK Manual Instrumentation Example
-============================================
+=============================================================
 
 This is an example of how to instrument Google GenAI SDK calls when configuring
 OpenTelemetry SDK and Instrumentations manually.

instrumentation-genai/opentelemetry-instrumentation-google-genai/examples/zero-code/README.rst

@@ -1,5 +1,5 @@
 OpenTelemetry Google GenAI SDK Manual Instrumentation Example
-============================================
+=============================================================
 
 This is an example of how to instrument Google GenAI SDK calls with zero code changes,
 using `opentelemetry-instrument`.

instrumentation-genai/opentelemetry-instrumentation-langchain/examples/manual/README.rst

@@ -1,12 +1,12 @@
 OpenTelemetry Langcahin Instrumentation Example
-============================================
+===============================================
 
 This is an example of how to instrument Langchain when configuring OpenTelemetry SDK and instrumentations manually.
 
-When :code:`main.py <main.py>`_ is run, it exports traces to an OTLP-compatible endpoint.
+When `main.py <main.py>`_ is run, it exports traces to an OTLP-compatible endpoint.
 Traces include details such as the span name and other attributes.
 
-Note: :code:`.env <.env>`_ file configures additional environment variables:
+Note: `.env <.env>`_ file configures additional environment variables:
 - :code:`OTEL_LOGS_EXPORTER=otlp` to specify exporter type.
 - :code:`OPENAI_API_KEY` open AI key for accessing the OpenAI API.
 - :code:`OTEL_EXPORTER_OTLP_ENDPOINT` to specify the endpoint for exporting traces (default is http://localhost:4317).
@@ -14,7 +14,7 @@ Note: :code:`.env <.env>`_ file configures additional environment variables:
 Setup
 -----
 
-Minimally, update the :code:`.env <.env>`_ file with your :code:`OPENAI_API_KEY`.
+Minimally, update the `.env <.env>`_ file with your :code:`OPENAI_API_KEY`.
 An OTLP compatible endpoint should be listening for traces http://localhost:4317.
 If not, update :code:`OTEL_EXPORTER_OTLP_ENDPOINT` as well.
 

instrumentation-genai/opentelemetry-instrumentation-langchain/examples/zero-code/README.rst

@@ -1,13 +1,13 @@
 OpenTelemetry Langchain Zero-Code Instrumentation Example
-======================================================
+=========================================================
 
 This is an example of how to instrument Langchain with zero code changes,
 using `opentelemetry-instrument`.
 
-When :code:`main.py <main.py>`_ is run, it exports traces to an OTLP-compatible endpoint.
+When `main.py <main.py>`_ is run, it exports traces to an OTLP-compatible endpoint.
 Traces include details such as the span name and other attributes.
 
-Note: :code:`.env <.env>`_ file configures additional environment variables:
+Note: `.env <.env>`_ file configures additional environment variables:
 - :code:`OTEL_LOGS_EXPORTER=otlp` to specify exporter type.
 - :code:`OPENAI_API_KEY` open AI key for accessing the OpenAI API.
 - :code:`OTEL_EXPORTER_OTLP_ENDPOINT` to specify the endpoint for exporting traces (default is http://localhost:4317).
@@ -15,7 +15,7 @@ Note: :code:`.env <.env>`_ file configures additional environment variables:
 Setup
 -----
 
-Minimally, update the :code:`.env <.env>`_ file with your :code:`OPENAI_API_KEY`.
+Minimally, update the `.env <.env>`_ file with your :code:`OPENAI_API_KEY`.
 An OTLP compatible endpoint should be listening for traces http://localhost:4317.
 If not, update :code:`OTEL_EXPORTER_OTLP_ENDPOINT` as well.
 

instrumentation-genai/opentelemetry-instrumentation-vertexai/examples/manual/README.rst

@@ -1,5 +1,5 @@
 OpenTelemetry VertexAI Instrumentation Example
-============================================
+==============================================
 
 This is an example of how to instrument VertexAI calls when configuring OpenTelemetry SDK and Instrumentations manually.
 
@@ -12,8 +12,8 @@ your VertexAI requests.
 Note: `.env <.env>`_ file configures additional environment variables:
 
 - `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` configures
-VertexAI instrumentation to capture prompt and completion contents on
-events.
+  VertexAI instrumentation to capture prompt and completion contents on
+  events.
 
 Setup
 -----

instrumentation-genai/opentelemetry-instrumentation-vertexai/examples/zero-code/README.rst

@@ -1,5 +1,5 @@
 OpenTelemetry VertexAI Instrumentation Example
-============================================
+==============================================
 
 This is an example of how to instrument VertexAI calls with zero code changes,
 using `opentelemetry-instrument`.

instrumentation/opentelemetry-instrumentation-urllib/README.rst

@@ -37,7 +37,7 @@ The hooks can be configured as follows:
 
     # `request_obj` is an instance of urllib.request.Request
     # `response` is an instance of http.client.HTTPResponse
-    def response_hook(span, request_obj, response)
+    def response_hook(span, request_obj, response):
         pass
 
     URLLibInstrumentor().instrument(

tox.ini

@@ -429,7 +429,7 @@ envlist =
     generate
     generate-workflows
     shellcheck
-    ruff
+    precommit
     typecheck
 
 [testenv]
@@ -1047,7 +1047,7 @@ commands_pre =
 commands =
   sh -c "find {toxinidir} -name \*.sh | xargs shellcheck --severity=warning"
 
-[testenv:ruff]
+[testenv:{precommit,ruff}]
 basepython: python3
 deps =
   -c {toxinidir}/dev-requirements.txt