Documentation: format docstrings for dev docs#3353
Open
C-Achard wants to merge 29 commits into
Open
Conversation
Add mdformat pre-commit hook (rev 1.0.0) with mdformat-myst to format Markdown files under docs/*.md. Update local pre-commit hook to exclude tools/docs_audits/ from the docs/notebooks checks. Also include tools/**/*.md in the docs_and_notebooks_report scan and add tools/docs_audits/** to its exclude list to avoid auditing generated/temporary audit files.
Align docstring and formatting settings to the NumPy convention: set docstring_style to 'numpy' and increase line_length to 120 in dev-docs/mkdocs.yml; update [tool.ruff.lint.pydocstyle] convention to 'numpy' and enable [tool.ruff.format].docstring-code-format in pyproject.toml. These changes ensure consistent docstring parsing/formatting across documentation tooling and linters.
Comment out the mdformat hook in .pre-commit-config.yaml because it currently breaks autorefs by replacing them with escaped links. Add explanatory comments and link to the related issue (KyleKing/mdformat-mkdocs#80). The commented block also shows a potential workaround pin (mdformat-mkdocs==5.2.0b2) for reference.
This reverts commit c99aa9d.
6 tasks
deruyter92
reviewed
Jun 2, 2026
Collaborator
deruyter92
left a comment
There was a problem hiding this comment.
I really like the idea in this PR, but would prefer to use google style instead of numpy.
By far most of our codebase currently uses google style (which is also our recommended style I believe?). If we want to align everything in google style, only a small fraction of the codebase would need to be readjusted (~36 files according to Claude).
What would you think about the following approach?
- Settle on google style in
pyproject.toml(as it was),mkdocs.yml, and sphinx (usingsphinx.ext.napoleon) - Use a basic conversion tool (e.g. pyment for the trivial conversions numpy -> google in ~36 files)
- Manual review for these files
- Agent-supported review for the more difficult (e.g. mixed) cases
- Linting to enforce
|
|
||
| # - repo: https://github.com/hukkin/mdformat | ||
| # Broken currently, replaces all autorefs with broken escaped links. | ||
| # See https://github.com/KyleKing/mdformat-mkdocs/issues/80 |
Collaborator
There was a problem hiding this comment.
Let's keep an eye on this issue.
| "*.ipynb" = [ "E402" ] | ||
| [tool.ruff.lint.pydocstyle] | ||
| convention = "google" | ||
| convention = "numpy" |
Collaborator
There was a problem hiding this comment.
I think we should stick with google style.
Collaborator
There was a problem hiding this comment.
We currently mix both, but google seems to be most prevalent:
| Style marker | Occurrences | Files | Where |
|---|---|---|---|
| Google Args: | ~501 | ~131 | |
| Google Returns: | ~370 | ~119 | Newer API (e.g. all pose_estimation_pytorch/ |
| NumPy Parameters | ~66 | ~36 | |
| NumPy Returns | ~31 | ~17 | Mostly older API (e.g. create_project/) |
(This requires us to update the mkdocs.yml accordingly)
Collaborator
Author
There was a problem hiding this comment.
Sounds good, I'm also in favor of making a minimal amount of changes and on a personal level prefer google style, so I definitely agree.
Collaborator
There was a problem hiding this comment.
I'll give it a try right now
- proper syntax highlighting - no >>> in code blocks - etc
C-Achard
commented
Jun 4, 2026
| None. | ||
| copy_videos (bool, optional): If this is set to True, the videos are copied to | ||
| the ``videos`` directory. If it is False, symlink of the videos are copied | ||
| to the project/videos directory. Note: on Windows: True is often necessary! |
Collaborator
Author
There was a problem hiding this comment.
Suggested change
| to the project/videos directory. Note: on Windows: True is often necessary! | |
| to the project/videos directory. Note: on Windows, True is necessary when not running in Administrator mode. The same applies whenever symlinks are disabled or unsupported. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Warning
This runs mdformat on all docs, which may conflict with the docs audit.We may want to revert c99aa9d to prevent issues.See #3336