Documentation: format docstrings for dev docs - #3353
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.
C-Achard
added
enhancement
This reverts commit c99aa9d.
deruyter92
left a comment
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 |
There was a problem hiding this comment.
Let's keep an eye on this issue.
- proper syntax highlighting - no >>> in code blocks - etc
Co-authored-by: Cyril Achard <cyril.achard@epfl.ch>
C-Achard
left a comment
C-Achard
left a comment
There was a problem hiding this comment.
Some intermediate comments, otherwise this is already amazing. Thanks a lot for the massive push on this!
|
Note: the conflicts should not be a problem as long as we preventively rename the params in the docstring. Then we can accept all current safely I think. |
|
@C-Achard thanks for your review. Valid points. I will pick this up later this week, unless you want to give it a go yourself. |
|
Working on it now! |
Changes rename "videotype" to "video_extensions" (cli.py: analyze_videos, create_labeled_video, plot_trajectories), "displayiters" to "display_iters" (compat.py and pose_estimation_tensorflow/training.py train_network docs), and capitalized/mismatched "Shuffles" to "shuffles" (generate_training_dataset/trainingsetmanipulation.py, compat.py, pose_estimation_tensorflow/core/evaluate.py).
Standardize and simplify example blocks across the codebase by removing doctest prompts (>>>), adjusting indentation/whitespace, and converting examples to plain code snippets for readability. Affects multiple modules including conda-environments/DEEPLABCUT.yaml and various deeplabcut/pose_estimation_pytorch, pose_tracking_pytorch, core, registry, modelzoo, runners, models, and post_processing files. Only formatting of docstrings and example sections.
Update docstrings and examples to use a clearer parameter name and correct example keys. Replaced occurrences of "videotype" with "video_extensions" across several modules (compat.py, create_project/new.py, modelzoo/video_inference.py, pose_estimation_tensorflow/predict_videos.py, pose_estimation_tensorflow/modelzoo/api/superanimal_inference.py, pose_tracking_pytorch/apis.py), and added a detailed description for the new video_extensions parameter in create_project/new.py. Also corrected example/parameter names in compat.py (displayiters -> display_iters and Shuffles -> shuffles) to match expected naming.
|
@deruyter92 Did some further cleanup, including fixing merge conflicts. |
deruyter92
left a comment
deruyter92
left a comment
There was a problem hiding this comment.
I manually reviewed all changed files again to make sure we are not introducing regressions. I fixed several additional cases (mainly the formatting of examples).
I think this PR is already hugely improving many docstrings. And for now it is the best we can do probably. We can always keep improving a few files on the go, once the dev-docs are online.
lets merge this as soon as possible, to avoid potential merge conflicts
|
Merging now! |
|
(Not squashing on purpose) |
2 participants
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