Display only the docstring of a class (Class.__doc__)

[ndonkoHenri]

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!

[ndonkoHenri]

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.

[ndonkoHenri]

Also, will please like to know how to display all but the class's docstring. Tried several things but couldnt get it out.

Basically in some section in want just the docstring and in another section i need all but it.

[pawamoy]

Try show_docstring_description: false 🙂

https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_description

[ndonkoHenri]

I tried this already, but only issue I have with it is that it removes admnitions too 🥹

This option is awesome, but in my usecase I will like the admonitions to be kept, similar to Raises:.

[ndonkoHenri]

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:

Here is my class:

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!

[pawamoy]

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.

[pawamoy]

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).

[ndonkoHenri]

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 to False to 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/set show_docstring_admonitions to false. Or using mkdocs-macros will be better/easier?

Fork this project and try to modify the internal logic? Or create an extension/plugin?