-
-
Notifications
You must be signed in to change notification settings - Fork 52
Display only the docstring of a class (Class.__doc__)
#302
-
For my usecase, I want to display just the content of Class's docstring (Class.__doc__) in my page.
I tried ::: package.Class.__doc__ but it failed:
ERROR - mkdocstrings: flet.Switch.__doc__ could not be found ERROR - Error reading page 'controls/switch.md': ERROR - Could not collect 'flet.Switch.__doc__'
Let me please know if it is possible, and if yes, how?
Thanks!
Beta Was this translation helpful? Give feedback.
All reactions
Replies: 3 comments 5 replies
-
Found a hack for my usecase:
::: flet.Switch options: show_root_heading: false show_bases: false members: false inherited_members: false show_root_toc_entry: false show_docstring_attributes: false show_docstring_functions: false show_docstring_examples: false show_docstring_parameters: false show_docstring_other_parameters: false show_docstring_raises: false show_docstring_receives: false show_docstring_returns: false show_docstring_warns: false show_docstring_yields: false
Will still like to know if it could be eased in some way.
Beta Was this translation helpful? Give feedback.
All reactions
-
🎉 2
-
Also, will please like to know how to display all but the class's docstring. Tried several things but couldnt get it out.
Screenshot 2025年07月22日 at 12 33 46
Basically in some section in want just the docstring and in another section i need all but it.
Beta Was this translation helpful? Give feedback.
All reactions
-
Try show_docstring_description: false 🙂
https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_description
Beta Was this translation helpful? Give feedback.
All reactions
-
I tried this already, but only issue I have with it is that it removes admnitions too 🥹
image
This option is awesome, but in my usecase I will like the admonitions to be kept, similar to Raises:.
Beta Was this translation helpful? Give feedback.
All reactions
-
Let me just brief my usecase and need, while hoping it is possible to have it :)
I have this structure for my docpage on the Switch class:
image
Here is my class:
image
Before the Examples, I want to display a the docstring of the class, precisely, only the summary and description. (no admonition/Raises etc)
And for the documentation of the class itself, which comes after the examples, I will like to remove the summary and description, as I already have it displayed in the intro.
With the 'hack' I came up with above and show_docstring_description: false, I achieved this so far:
Only last thing I want to achieve is the admonition not to be shown in the intro (first image) but in the class doc (second image). 🥹
Thanks!
Beta Was this translation helpful? Give feedback.
All reactions
-
I see, thanks for explaining your use-case 🙂
Unfortunately, if we implement a show_docstring_admonitions option, and untie show_docstring_description from admonitions, this would be a breaking change. I don't see how we can reconcile both options in a backward compatible way 🤔 I was going to suggest using https://mkdocstrings.github.io/griffe-warnings-deprecated/ but the result would be almost the same, you'd only get a deprecated label next to your object heading.
Beta Was this translation helpful? Give feedback.
All reactions
-
IMO admonitions should be treated as part of the docstring body/description, since they can appear anywhere in the docstring, whether they're written as Google-style admonitions or Markdown admonitions (using whatever syntax/markup and according extension).
Beta Was this translation helpful? Give feedback.
All reactions
-
IMO admonitions should be treated as part of the docstring body/description, since they can appear anywhere in the docstring, whether they're written as Google-style admonitions or Markdown admonitions (using whatever syntax/markup and according extension).
Yeah, that would make sense.
Thanks for your insight.
What options do you please see for me, if I want to implement this for personal usage though?
Specs:
- dont remove admonitions when using
show_docstring_description: false. Only the summary and description. - a prop (ex:
show_docstring_admonitions) to show/remove admonitions. In the intro of my doc-page, I will set toFalseto satisfy my usecase. - (must not exist, but for simplicity/convenience) have one new property (ex:
summary_and_description_only) which will represent the props in the 'hack' above. It will additionally wrap/setshow_docstring_admonitionstofalse. Or using mkdocs-macros will be better/easier?
Fork this project and try to modify the internal logic? Or create an extension/plugin?
Beta Was this translation helpful? Give feedback.