chore: guard against Sphinx/RST markup returning to docstrings

[vnaren23]

Follow-up to #1910 (merged), which converted the Sphinx roles, directives and literal-block markers in our docstrings to their Markdown/Google equivalents.

Implements @gheorghitahurmuz's review suggestion on that PR.

Why

The docs site renders docstrings through mkdocstrings with the Google parser, which treats them as Markdown. RST markup therefore leaks through verbatim onto the published API pages — which is exactly how #1910 started, with :meth:retrieve_v3`` and Basic usage:: visible on https://uipath.github.io/uipath-python/core/entities/. Nothing currently stops it coming back.

Change

Two pygrep hooks in .pre-commit-config.yaml:

Hook	Catches
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

Two deltas from the suggested snippet, both easy to drop if you'd rather not:

1. Added ref to the role alternation — same family, and docs: render docstring cross-references as Markdown, not Sphinx RST #1910 stripped those too.
2. Added the second hook for the trailing ::. That was the third RST-ism docs: render docstring cross-references as Markdown, not Sphinx RST #1910 fixed (Basic usage:: rendered with a stray extra colon), and it is the one most likely to be reintroduced by muscle memory.

Both are scoped to ^packages/[^/]+/src/.*\.py$ exactly as suggested. That scope is load-bearing, not incidental: test docstrings still use RST roles, and since they are never rendered, #1910 deliberately left them alone — widening the scope would fail immediately on them.

Verification

• Both hooks pass on the current tree.
• Against the pre-docs: render docstring cross-references as Markdown, not Sphinx RST #1910 copy of _entities_service.py, they fail with 69 and 66 offending lines respectively — i.e. they would have caught the original bug.
• Checked the suggested pattern's literal space in \.\. [a-z-]+:: in case pre-commit shlex-split the entry and silently dropped the directive half. It does not: pygrep.run_hook builds cmd = (sys.executable, '-m', __name__, *args, entry), passing entry as a single argv element. Confirmed empirically against a directive-only probe file, so the pattern is used verbatim.

One unrelated note: pre-commit run --all-files also fails ruff / ruff-format on six files under .github/scripts/. That drift is pre-existing on main (verified) and untouched here.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🔵 Needs a closer look

Both guards can be bypassed by valid whitespace variations.

Review effort: Lite
Findings: None

What changed in this PR

Adds scoped pre-commit checks to prevent Sphinx/RST markup from returning to rendered source docstrings.

Changes:

• Detects RST roles and directives.
• Detects trailing :: literal-block markers.
• Limits checks to package source files.

The directive pattern should allow arbitrary whitespace, and the literal-block pattern should allow trailing spaces.

File	Description
.pre-commit-config.yaml	Adds scoped pygrep hooks for RST syntax detection.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud