docs: render docstring cross-references as Markdown, not Sphinx RST by vnaren23 · Pull Request #1910 · UiPath/uipath-python

vnaren23 · 2026-09-24T10:38:24Z

Problem

The docs site renders docstrings via mkdocstrings with the Google parser, which treats docstring bodies as Markdown. Sphinx cross-reference roles in our docstrings therefore leak through verbatim onto the published pages.

Visible today on https://uipath.github.io/uipath-python/core/entities/:

Async variant of :meth:retrieve_v3 `:class:`EntitiesService keeps the existing sdk.entities.* API flat…
Examples: Basic usage**::**

The same leakage affects every other mkdocstrings-backed page whose module uses these roles (guardrails, governance, assets, tasks, evaluators, …).

Fix

Docstring text only — no code, signature, or behavior changes.

Was (RST)	Now (Markdown / Google)
:class:`Foo` , :data:`X` , :attr:`y` , :mod:`m`	`Foo`
:class:`~pkg.mod.Foo`	`Foo` (matches Sphinx's `~` = last component only)
:meth:`bar` , :func:`baz`	`bar()` (matches Sphinx's default `add_function_parentheses`)
`Basic usage::`	`Basic usage:` — the indented block already renders as a code block; only the stray colon was visible
`.. warning::`	a Google `Warning:` section, which griffe parses into a real admonition
`.. code-block:: python`, and the `Example::` blocks ruff D412 would then flag	fenced ```python blocks
the two `:param:` / `:return:` fields in `EntityRecord.from_data`	Google-style `Args:` / `Returns:`

Plain code spans were chosen over mkdocstrings autorefs ([Foo][]) deliberately: many targets are private services or live in modules that are not part of the nav, so autorefs would resolve to broken links or emit build warnings.

Scope is packages/*/src — 49 files, 275 role occurrences across uipath, uipath-core, and uipath-platform. Test-module docstrings still use RST roles; they are not rendered anywhere, so they are left alone.

Verification

grep confirms zero remaining :role: / :: / .. directive:: occurrences under packages/*/src.
ruff check passes on all three packages; ruff format --check reports all 49 touched files already formatted.
Parsed uipath.platform.entities._entities_service with griffe's Google parser: 223 docstrings, 0 sections containing RST residue, and the Examples: sections still yield their code blocks.

Fixed

Current

🤖 Generated with Claude Code

The docs site renders docstrings through mkdocstrings with the Google parser, which treats docstring bodies as Markdown. Sphinx roles such as `:class:`Foo`` and `:meth:`bar`` therefore leaked through verbatim onto the published API pages (e.g. /core/entities/), as did the RST literal- block marker `::` and the `.. warning::` / `.. code-block::` directives. Convert them to their Markdown/Google equivalents across all three packages' sources: - `:class:`/`:data:`/`:attr:`/`:mod:` -> inline code span; `~`-prefixed targets keep only the last component, matching Sphinx's rendering. - `:meth:`/`:func:` -> inline code span with `()`, matching Sphinx's default `add_function_parentheses`. - Trailing `::` -> `:` (the indented block already renders as a code block in Markdown; only the stray colon was visible). - `.. warning::` -> a Google `Warning:` section, which griffe parses as an admonition. - `.. code-block:: python` and the `Example::` blocks that ruff's D412 would then flag -> fenced ```python blocks. - The two stray `:param:`/`:return:` fields in `EntityRecord.from_data` -> Google-style `Args:`/`Returns:`. Docstring text only; no behavior changes. `ruff check` and `ruff format --check` pass on every touched file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Copilot

Copilot review overview

🟢 Approval recommended

No unresolved review comments remain, and the changes are documentation-only.

Review effort: Lite
Findings: None

What changed in this PR

Updates source docstrings from Sphinx RST to Markdown/Google syntax for correct mkdocstrings rendering, without runtime changes.

Changes:

Replaced cross-reference roles with Markdown code spans.
Converted directives and literal blocks to Markdown/Google equivalents.
Converted EntityRecord.from_data fields to Google-style documentation.

File	Summary
`packages/uipath/src/uipath/functions/factory.py`	Updated class references.
`packages/uipath/src/uipath/functions/debug.py`	Updated literal-block syntax.
`packages/uipath/src/uipath/eval/runtime/runtime.py`	Updated function references.
`packages/uipath/src/uipath/eval/evaluators/dataset_evaluator_factory.py`	Updated evaluator references.
`packages/uipath/src/uipath/eval/evaluators/base_dataset_evaluator.py`	Updated class references.
`packages/uipath/src/uipath/agent/models/agent.py`	Updated class references.
`packages/uipath/src/uipath/_cli/_governance/yaml_index.py`	Updated governance references.
`packages/uipath/src/uipath/_cli/_governance/__init__.py`	Updated API references.
`packages/uipath/src/uipath/_cli/_governance_bootstrap.py`	Updated governance references.
`packages/uipath-platform/src/uipath/platform/orchestrator/_assets_service.py`	Updated method references.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/user_prompt_attacks.py`	Updated validator references.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/prompt_injection.py`	Updated validator references.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/pii.py`	Updated validator references.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/llm_as_judge.py`	Updated validator references.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/intellectual_property.py`	Updated validator references.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/harmful_content.py`	Updated validator references.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/custom.py`	Updated references and examples.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/byo.py`	Updated references and code fencing.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/validators/_base.py`	Updated references and examples.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/_registry.py`	Updated function references.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/_models.py`	Updated class references.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/_guardrail.py`	Updated API references.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/_core.py`	Updated references and examples.
`packages/uipath-platform/src/uipath/platform/guardrails/decorators/_actions.py`	Updated class references.
`packages/uipath-platform/src/uipath/platform/governance/policy.py`	Updated module references.
`packages/uipath-platform/src/uipath/platform/governance/compensate.py`	Updated module references.
`packages/uipath-platform/src/uipath/platform/governance/_live_track_event_dispatcher.py`	Updated references and examples.
`packages/uipath-platform/src/uipath/platform/governance/_governance_service.py`	Updated service references.
`packages/uipath-platform/src/uipath/platform/governance/_governance_provider.py`	Updated provider references.
`packages/uipath-platform/src/uipath/platform/errors/_datafabric_error.py`	Updated error references.
`packages/uipath-platform/src/uipath/platform/entities/entities.py`	Updated references and parameter documentation.
`packages/uipath-platform/src/uipath/platform/entities/_entity_schema_service.py`	Updated service references.
`packages/uipath-platform/src/uipath/platform/entities/_entity_ontology_service.py`	Updated service references.
`packages/uipath-platform/src/uipath/platform/entities/_entity_data_service.py`	Updated service and model references.
`packages/uipath-platform/src/uipath/platform/entities/_entities_service.py`	Updated references and examples.
`packages/uipath-platform/src/uipath/platform/common/_reference_context.py`	Updated references and examples.
`packages/uipath-platform/src/uipath/platform/common/_execution_context.py`	Updated context references.
`packages/uipath-platform/src/uipath/platform/common/_base_service.py`	Updated helper references.
`packages/uipath-platform/src/uipath/platform/agenthub/remote_a2a.py`	Converted warning directives.
`packages/uipath-platform/src/uipath/platform/agenthub/_remote_a2a_service.py`	Converted warnings and examples.
`packages/uipath-platform/src/uipath/platform/action_center/_tasks_service.py`	Updated method references.
`packages/uipath-core/src/uipath/core/governance/providers.py`	Updated references and example syntax.
`packages/uipath-core/src/uipath/core/governance/models.py`	Updated class references.
`packages/uipath-core/src/uipath/core/governance/exceptions.py`	Updated method and class references.
`packages/uipath-core/src/uipath/core/governance/config.py`	Updated module and method references.
`packages/uipath-core/src/uipath/core/governance/__init__.py`	Updated class references.
`packages/uipath-core/src/uipath/core/feature_flags/feature_flags.py`	Updated references and examples.
`packages/uipath-core/src/uipath/core/adapters/evaluator.py`	Updated protocol references.
`packages/uipath-core/src/uipath/core/adapters/__init__.py`	Updated protocol references.

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

sonarqubecloud · 2026-09-24T10:46:24Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

gheorghitahurmuz · 2026-09-28T10:04:55Z

nit: add a guard so RST roles don't come back (follow up PR maybe). something like:

 - repo: local
   hooks:
     - id: no-rst-roles
       name: No Sphinx/RST roles in docstrings (docs use mkdocstrings/Markdown)
       language: pygrep
       entry: ':(class|meth|func|mod|attr|data|exc|obj):`|^\s*\.\. [a-z-]+::'
       files: ^packages/[^/]+/src/.*\.py$

vnaren23 · 2026-09-28T10:17:55Z

Added in #1913 — thanks, good call. Two small deltas from your snippet, both easy to drop:

Added ref to the role alternation, same family as the rest.
Added a second hook for the trailing :: literal-block marker — that was the third RST-ism this PR fixed (Basic usage:: rendered with a stray extra colon) and the one most likely to come back by muscle memory.

Kept your files: ^packages/[^/]+/src/.*\.py$ scope as-is. It turns out to be load-bearing: test docstrings still use RST roles and are never rendered, so this PR left them alone deliberately — widening the scope would fail on them straight away.

I did check whether the literal space in \.\. [a-z-]+:: would get shlex-split and silently drop the directive half of the pattern. It doesn't — pygrep.run_hook builds cmd = (sys.executable, '-m', __name__, *args, entry), so entry stays one argv element. Used verbatim.

Verified both hooks pass on the current tree and report 69 / 66 offending lines against the pre-merge copy of _entities_service.py.

Copilot AI lite review requested due to automatic review settings September 24, 2026 10:38

github-actions Bot added test:uipath-langchain Triggers tests in the uipath-langchain-python repository test:uipath-runtime test:uipath-integrations labels Sep 24, 2026

Copilot started reviewing on behalf of vnaren23 September 24, 2026 10:38 View session

Copilot AI reviewed Sep 24, 2026

View reviewed changes

gheorghitahurmuz approved these changes Sep 28, 2026

View reviewed changes

vnaren23 merged commit 467f609 into main Sep 28, 2026
97 of 99 checks passed

vnaren23 deleted the docs/sphinx-roles-to-markdown branch September 28, 2026 10:14

vnaren23 mentioned this pull request Sep 28, 2026

chore: guard against Sphinx/RST markup returning to docstrings #1913

Merged

Navigation Menu

docs: render docstring cross-references as Markdown, not Sphinx RST - #1910

docs: render docstring cross-references as Markdown, not Sphinx RST#1910
vnaren23 merged 1 commit into
mainfrom
docs/sphinx-roles-to-markdown

vnaren23 commented Sep 24, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

sonarqubecloud Bot commented Sep 24, 2026

Uh oh!

gheorghitahurmuz commented Sep 28, 2026

Uh oh!

Uh oh!

vnaren23 commented Sep 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

vnaren23 commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Fix

Verification

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟢 Approval recommended

Uh oh!

sonarqubecloud Bot commented Sep 24, 2026

Quality Gate passed

Uh oh!

gheorghitahurmuz commented Sep 28, 2026

Uh oh!

Uh oh!

vnaren23 commented Sep 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vnaren23 commented Sep 24, 2026 •

edited

Loading