Skip to content

Add prek hook to forbid double backticks in docstrings #1822

@nathanjmcdougall

Description

@nathanjmcdougall

Problem

Agents (and developers) sometimes write Python docstrings using RST double-backtick markup (e.g. install_requires) when single backticks should be used instead. This was caught in code review on PR #1795.

Double backticks are RST-style code spans, but this project does not use RST-rendered docstrings. Single backticks are preferred for inline code references in docstrings.

Solution

Add a bespoke prek hook that scans Python files and fails if any docstring lines contain ... (double backtick patterns).

  • The hook should be a CLI script accepting a list of files
  • It should parse Python files and check only docstring content (not code)
  • Should report file/line/column of violations
  • Example pattern to forbid: foo

Agent Skill Update

Update the relevant agent skills (e.g. usethis-python-code) to explicitly note: do NOT use double backticks in docstrings. Use single backticks for inline code references.

Metadata

Metadata

Labels

No labels
No labels

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions