docs: improve docstrings configuration#371
Merged
FlorianDeconinck merged 3 commits intoJan 28, 2026
Merged
Conversation
This PR improves the auto-generated docs from docstrings. The filter, makes sure we hide all methods/constants/attribues starting with at least one underscore. It adds an exception for `__init__(...)` methods. `show_if_no_docstrings` tells the system to show all methods/constants/attributes even if they don't have a docstring attached. This is especially useful for things like enums, where the enum name can be sufficient. `members_order` and `group_by_category` relate to how entries on pages are sorted/grouped. The default is "ungrouped" and in alphabetical order. Imo that leads to weirdly looking pages. This PR suggest to keep the order as in source code and group by category (e.g. constants, classes, ...)
romanc
changed the title
FlorianDeconinck
requested changes
Jan 28, 2026
| options: | ||
| filters: | ||
| - "!^_" | ||
| - "^__init__$" |
Collaborator
There was a problem hiding this comment.
Can we get an exception for __call__ as well please? Not that we use it in NDSL too much, but my hunch is that the execution operator should be doc'ed
Collaborator
Author
There was a problem hiding this comment.
Makes sense, I've added an exception. I started to hide them because in case of the Backend it started to show methods like __add__ and __radd__.
Collaborator
Author
|
Added another commit to cut down on warnings emitted when building the docs. Not perfect yet, but there were some easy things to fix. |
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.
Description
This PR is a follow-up from #370 where I've had a look at the auto-generated docs of the NDSL backend. The PR improves the auto-generated docs from docstrings.
The filter, makes sure we hide all methods/constants/attribues starting with at least one underscore. It adds an exception for
__init__(...)methods.show_if_no_docstringstells the system to show all methods/constants/attributes even if they don't have a docstring attached. This is especially useful for things like enums, where the enum name can be sufficient.members_orderandgroup_by_categoryrelate to how entries on pages are sorted/grouped. The default is "ungrouped" and in alphabetical order. Imo that leads to weirdly looking pages. This PR suggest to keep the order as in source code and group by category (e.g. constants, classes, ...)How has this been tested?
Locally running
mkdocs serve.Checklist