Background and Current State
Currently, the DiracX codebase suffers from an inconsistency in its docstring conventions. A review of the code reveals a mix of Google Style docstrings and legacy reStructuredText (reST) style docstrings.
As DiracX utilizes MkDocs (and Markdown) for its documentation rendering rather than Sphinx, this mix creates both readability issues for developers and architectural friction for our documentation generators (like mkdocstrings).
The Problem with the Current Inconsistency
- Native Compatibility:
mkdocstrings is fundamentally designed to parse the Google docstring convention natively and seamlessly convert it into Markdown. Conversely, parsing reST tags (:param:, :type:) in an MkDocs environment is an architectural mismatch that requires heavy workarounds and often results in poorly formatted HTML output.
- Readability: Having two different styles across the repository increases cognitive load for developers reading the raw code.
- DRY Principle Violation: reST forces developers to duplicate type hints inside the docstring, ignoring the modern Python type annotations (PEP 484) that DiracX heavily uses.
Pros & Cons Comparison
To align the team on the best path forward, here is a breakdown of why standardizing purely on the Google convention is the optimal architectural choice for DiracX:
| Feature / Aspect |
Google Style (Proposed Standard) |
reStructuredText (Current Legacy) |
| MkDocs / Markdown Integration |
Native & Flawless (via mkdocstrings) |
Poor (Requires complex plugins/hacks) |
| Raw Code Readability |
High (Clean sections: Args:, Returns:) |
Low (Cluttered with explicit :tags:) |
| DRY (Type Hinting) |
Excellent (Extracts types from signatures) |
Redundant (Types must be written twice) |
| Contributor Onboarding |
Intuitive (Lower barrier to entry) |
Steep curve (Syntax is strict and verbose) |
| Legacy Portability |
N/A |
Pro: Easier copy/pasting from legacy DIRAC. (Note: As DiracX is a modern rewrite, this benefit is practically negligible). |
Proposed Solution & Tooling
We should officially deprecate the reST docstring style and mandate the Google Style across the entire DiracX repository.
To enforce this without relying on manual code reviews, we can leverage our existing linter. Since the project already relies on Ruff, we can enforce the Google convention automatically by adding the following to our pyproject.toml:
[tool.ruff.lint.pydocstyle]
convention = "google"
This will integrate the docstring format check directly into our CI/CD pipeline, ensuring that all future Pull Requests maintain perfect consistency.
Migration Strategy
- Change all non-Google style docstrings to Google style.
- Apply the Ruff configuration to enforce the rule for all new code.
Feedback Requested
I would like to bring this up during a DDev to agree on standardizing our documentation architecture. Feedback on the automated enforcement via Ruff is highly appreciated!
Background and Current State
Currently, the DiracX codebase suffers from an inconsistency in its docstring conventions. A review of the code reveals a mix of Google Style docstrings and legacy reStructuredText (reST) style docstrings.
As DiracX utilizes MkDocs (and Markdown) for its documentation rendering rather than Sphinx, this mix creates both readability issues for developers and architectural friction for our documentation generators (like
mkdocstrings).The Problem with the Current Inconsistency
mkdocstringsis fundamentally designed to parse the Google docstring convention natively and seamlessly convert it into Markdown. Conversely, parsing reST tags (:param:,:type:) in an MkDocs environment is an architectural mismatch that requires heavy workarounds and often results in poorly formatted HTML output.Pros & Cons Comparison
To align the team on the best path forward, here is a breakdown of why standardizing purely on the Google convention is the optimal architectural choice for DiracX:
mkdocstrings)Args:,Returns:):tags:)Proposed Solution & Tooling
We should officially deprecate the reST docstring style and mandate the Google Style across the entire DiracX repository.
To enforce this without relying on manual code reviews, we can leverage our existing linter. Since the project already relies on Ruff, we can enforce the Google convention automatically by adding the following to our
pyproject.toml:This will integrate the docstring format check directly into our CI/CD pipeline, ensuring that all future Pull Requests maintain perfect consistency.
Migration Strategy
Feedback Requested
I would like to bring this up during a DDev to agree on standardizing our documentation architecture. Feedback on the automated enforcement via Ruff is highly appreciated!