Skip to content

docs: Fix google-style docstrings in duties.py#468

Closed
mushitoriami wants to merge 3 commits into
mkdocstrings:mainfrom
mushitoriami:doc-patch-1
Closed

docs: Fix google-style docstrings in duties.py#468
mushitoriami wants to merge 3 commits into
mkdocstrings:mainfrom
mushitoriami:doc-patch-1

Conversation

@mushitoriami

Copy link
Copy Markdown
Contributor

For reviewers

  • I did not use AI
  • I used AI and thoroughly reviewed every code/docs change

Description of the change

In the docstrings in duties.py, there are some Example: occurrences, but these should be Examples: (https://mkdocstrings.github.io/griffe/reference/docstrings/#google-section-examples). This issue causes broken document format (https://mkdocstrings.github.io/griffe/guide/contributors/commands/#check-quality, https://mkdocstrings.github.io/griffe/guide/contributors/commands/#check-types ).

@pawamoy

pawamoy commented Jun 22, 2026

Copy link
Copy Markdown
Member

Thanks @mushitoriami! I don't understand though, the Example section should definitely work, it should create an admonition. If I load the code with Griffe and parse the docstring, the section is correctly parsed as an admonition 🙃 So I don't understand yet why it's not rendered as such.

@pawamoy

pawamoy commented Jun 22, 2026

Copy link
Copy Markdown
Member

Ah, right, I'm dog-fooding the auto docstrings parser, and in this case no style is inferred (so no Google-style admonition parsing). The fix is to either fix the function that infers the style, or set google in mkdocs.yml. Would you like to update the PR?

@mushitoriami

Copy link
Copy Markdown
Contributor Author

@pawamoy Thanks for the comment. I've updated to set the style option.

@mushitoriami

Copy link
Copy Markdown
Contributor Author

It looks like the CI failure is caused by ty==0.0.52, which was released today.

@pawamoy

pawamoy commented Jun 23, 2026

Copy link
Copy Markdown
Member

Thanks!
Yeah I'll fix CI elsewhere.

@pawamoy

pawamoy commented Jun 23, 2026

Copy link
Copy Markdown
Member

Actually, lets rather add some patterns to the function that infers style. Let me do that in another PR. Thanks again for the report!

@pawamoy pawamoy closed this Jun 23, 2026
@mushitoriami mushitoriami deleted the doc-patch-1 branch June 23, 2026 11:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants