Unable to get docstring summary, and supress the remainder of the docstring

bschollnick commented 6 months ago

Description of the bug

From my reading of the documentation, I don't see any way to supress the docstring, and only show the summary line(s) of the docstring. We are hoping to have 2 different blocks.... One will only show the summary (being a "non-technical") summary, and then another in a collapsed annotation that has the whole 9 yards.

This allows the documentation to be used for non-technical (non-programmers), using the summary only listing, And allow programmers to view the same documentation.

I see a "summary" option, https://github.com/mkdocstrings/python/blob/eaf9b8240069f7369f401fe048892043c8b173d3/src/mkdocstrings_handlers/python/handler.py#L157 But it seems to do nothing...

e.g. summary: true, appears to do nothing.

To Reproduce

 Example:

::: application.checkers.hoster.hostingclass
    options:
      show_source: false
      heading_level: 2
      parameter_headings: false
      merge_init_into_class: true
      docstring_options:
        ignore_init_summary: false
        trim_doctest_flags: false
      summary: true
      show_docstring_parameters: false
      show_docstring_raises: false
      show_docstring_receives: false
      show_docstring_yields: false
      show_docstring_warns: false
      show_docstring_description: false
      show_docstring_returns: false
      show_docstring_examples: false

As mentioned, using mkdocs w/mkdocstring[python] plugin, seems to work fine except I can't get the summary option to work.

Expected behavior

The ability to show the docstring summary, without the rest of the docstring.

Environment information

python -m mkdocstrings_handlers.python.debug  # | xclip -selection clipboard

> No module named mkdocstrings_handlers.python.debug

The following libraries are loaded: mkdocs 1.5.3 Project documentation with Markdown. mkdocs-autorefs 1.0.1 Automatically link across pages in MkDocs. mkdocs-material 9.5.10 Documentation that simply works mkdocs-material-extensions 1.3.1 Extension pack for Python Markdown and MkDocs Material. mkdocstrings 0.24.1 Automatic documentation from sources, for MkDocs. mkdocstrings-python 1.7.3 A Python handler for mkdocstrings.

pawamoy commented 6 months ago

Hello, thanks for the report.

The summary option is documented here: https://mkdocstrings.github.io/python/usage/configuration/members/#summary. It's used to automatically create lists/tables of attributes, functions, classes, and submodules, using the docstring summary of each object.

For example, see it in action here: https://mkdocstrings.github.io/python/reference/mkdocstrings_handlers/python/rendering/. The "classes" and "functions" lists are auto-generated. Each name is a link that will bring you to the full documentation of the relevant object.

If this option does nothing for you, it's probably because you are not using the Insiders version of mkdocstrings-python: this feature is available to sponsors only (as explained in the docs). It will become available to everyone once the $1000/month goal is reached, see https://mkdocstrings.github.io/python/insiders/#1000-gravifridge-user-manual :slightly_smiling_face:

Would this option work for you, or would you prefer to get an additional option like show_docstring_summary, that you could set to true and combine with show_docstring_description: false in order to only show the summary of a given object?

bschollnick commented 6 months ago

Yes, an excellent option would be show_docstring_summary: true/false boolean would easily solve that issue...

mkdocstrings / python