From 699560cdd56318d998c70b71fd2660a56abcdc8e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 30 Mar 2026 23:55:29 +0000 Subject: [PATCH 1/3] Initial plan From 0c1d6eb2f8b508a7747859ad4f6a0ca506bb0946 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 30 Mar 2026 23:58:55 +0000 Subject: [PATCH 2/3] Add docstring backtick style convention to usethis-python-code skill Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/d73e16e3-0b7f-41bc-8cf7-67d8cda93221 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> --- .agents/skills/usethis-python-code/SKILL.md | 22 ++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/.agents/skills/usethis-python-code/SKILL.md b/.agents/skills/usethis-python-code/SKILL.md index 9be1e8f7..02e6040b 100644 --- a/.agents/skills/usethis-python-code/SKILL.md +++ b/.agents/skills/usethis-python-code/SKILL.md @@ -4,13 +4,33 @@ description: Guidelines for Python code design decisions such as when to share v compatibility: usethis, Python license: MIT metadata: - version: "1.2" + version: "1.3" --- # Python Code Guidelines Use the `usethis-python-code-modify` skill when making code changes. This skill covers design decisions that inform those changes. +## Docstring code references + +When referencing code names (functions, classes, modules, parameters, etc.) in docstrings, always use single backticks (`` ` ``), not double backticks (``` `` ```). This applies to all identifiers mentioned in docstring text. + +### Example + +```python +# Good: single backticks +def add_dep(name: str) -> None: + """Add a dependency using `uv add`.""" + +# Bad: double backticks (RST style) +def add_dep(name: str) -> None: + """Add a dependency using ``uv add``.""" +``` + +### Why + +The project uses Markdown-compatible formatting for docstrings. Single backticks are the Markdown standard for inline code, and the project's export hooks normalize double backticks to single backticks. Using single backticks from the start avoids this normalization and keeps docstrings consistent with their rendered output. + ## Avoiding unnecessary duplication When writing new code or replacing a dependency with custom code, prefer a single shared implementation over duplicating logic across modules. Only introduce duplication when there is a concrete, present-day reason to do so. From 9963ecb0c4c486cb22391a99855453c811be6670 Mon Sep 17 00:00:00 2001 From: Nathan McDougall Date: Wed, 1 Apr 2026 10:56:18 +1300 Subject: [PATCH 3/3] Comply with markdown linter --- .agents/skills/usethis-python-code/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/usethis-python-code/SKILL.md b/.agents/skills/usethis-python-code/SKILL.md index 02e6040b..578d3063 100644 --- a/.agents/skills/usethis-python-code/SKILL.md +++ b/.agents/skills/usethis-python-code/SKILL.md @@ -13,7 +13,7 @@ Use the `usethis-python-code-modify` skill when making code changes. This skill ## Docstring code references -When referencing code names (functions, classes, modules, parameters, etc.) in docstrings, always use single backticks (`` ` ``), not double backticks (``` `` ```). This applies to all identifiers mentioned in docstring text. +When referencing code names (functions, classes, modules, parameters, etc.) in docstrings, always use single backticks (`` ` ``), not double backticks (` `` `). This applies to all identifiers mentioned in docstring text. ### Example