From 93fb2ecd3e5104ff57f41be80b9f4309f0181b37 Mon Sep 17 00:00:00 2001 From: Naren Date: Mon, 28 Sep 2026 15:47:21 +0530 Subject: [PATCH] chore: guard against Sphinx/RST markup returning to docstrings Follow-up to #1910, which converted Sphinx roles, directives and literal- block markers in docstrings to their Markdown/Google equivalents. The docs site renders docstrings through mkdocstrings with the Google parser, which treats them as Markdown, so RST markup leaks through verbatim onto the published API pages. Add two pygrep pre-commit hooks so it does not creep back: - no-rst-roles: `:class:`/`:meth:`/`:func:`/`:mod:`/`:attr:`/`:data:`/ `:exc:`/`:obj:`/`:ref:` roles and `.. directive::` lines. - no-rst-literal-blocks: the trailing `::` literal-block marker. Both are scoped to `^packages/[^/]+/src/.*\.py$`. Test docstrings still use RST roles and are never rendered, so widening the scope would only produce noise. Verified: both hooks pass on the current tree, and against the pre-#1910 copy of _entities_service.py they report 69 and 66 offending lines respectively. Co-Authored-By: Claude Opus 5 (1M context) --- .pre-commit-config.yaml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d584e5017..0f8f17f53 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -5,3 +5,20 @@ repos: - id: ruff args: [ --fix ] - id: ruff-format + +# The docs site renders docstrings through mkdocstrings with the Google +# parser, which treats them as Markdown, so Sphinx/RST markup leaks through +# verbatim onto the published API pages. Scoped to src/ because test +# docstrings are never rendered. +- repo: local + hooks: + - id: no-rst-roles + name: No Sphinx/RST roles or directives in docstrings (docs render as Markdown) + language: pygrep + entry: ':(class|meth|func|mod|attr|data|exc|obj|ref):`|^\s*\.\. [a-z-]+::' + files: ^packages/[^/]+/src/.*\.py$ + - id: no-rst-literal-blocks + name: No RST literal-block markers in docstrings (use a fenced code block) + language: pygrep + entry: '::$' + files: ^packages/[^/]+/src/.*\.py$