Skip to content

fmt_docstrings: Use string template syntax for docstring placeholders and support curly braces in docstrings #4210

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

fmt_docstrings: Use string template syntax for docstring placeholders and support curly braces in docstrings #4210

wants to merge 8 commits into from

Conversation

@seisman
Copy link
Member

@seisman seisman commented Nov 15, 2025 •
edited
Loading

Description of proposed changes

See #3815 for the original issue report and the solution.

This PR uses the string.Template method to avoid using curly braces for docstring placeholders.

Changes in this PR include:

  • Update docstring placeholder syntax from {projection} to $projection
  • Rename placeholder table-classes to table_classes because string.Template doesn't work well with -
  • Replace {{/}} with {/} in LaTeX math equations

Fixes #3815.

Preview:

Wrappers with math equations:

An example page with updated docstring placeholder syntax:

@seisman seisman force-pushed the docstring/placeholder branch 4 times, most recently from c50845b to f44e356 Compare November 15, 2025 09:32
@seisman seisman added the maintenance Boring but important stuff for the core devs label Nov 15, 2025
@seisman seisman modified the milestone: 0.18.0 Nov 15, 2025
@seisman seisman mentioned this pull request Nov 15, 2025
Open
@seisman seisman changed the title fmt_docstrings: Support raw curly braces in docstrings WIP: fmt_docstrings: Support raw curly braces in docstrings Nov 15, 2025
@seisman seisman force-pushed the docstring/placeholder branch from 03ac916 to 7c1b978 Compare November 15, 2025 11:19
@seisman seisman force-pushed the docstring/placeholder branch 2 times, most recently from 565d256 to f9e1a80 Compare November 15, 2025 11:23
@seisman seisman force-pushed the docstring/placeholder branch from f9e1a80 to 99dd6e8 Compare November 15, 2025 11:25
@seisman seisman changed the title WIP: fmt_docstrings: Support raw curly braces in docstrings fmt_docstrings: Support raw curly braces in docstrings Nov 15, 2025
@seisman seisman changed the title fmt_docstrings: Support raw curly braces in docstrings fmt_docstrings: Use string template syntax for docstring placeholders and support curly braces in docstrings Nov 15, 2025
@seisman seisman added the needs review This PR has higher priority and needs review. label Nov 15, 2025
@seisman seisman marked this pull request as ready for review November 15, 2025 12:06
@seisman seisman added final review call This PR requires final review and approval from a second reviewer and removed needs review This PR has higher priority and needs review. labels Nov 23, 2025
@seisman
Copy link
Member Author

seisman commented Nov 23, 2025

This is a big change in how the docstrings are written. Hopefully, @weiji14 can give this PR a review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@yvonnefroehlich yvonnefroehlich yvonnefroehlich approved these changes

Assignees

No one assigned

Labels

final review call This PR requires final review and approval from a second reviewer maintenance Boring but important stuff for the core devs

Projects

None yet

Milestone

0.18.0

Development

Successfully merging this pull request may close these issues.

fmt_docstring: Allow raw curly braces {} to avoid KeyError

3 participants

@seisman @yvonnefroehlich