python icon indicating copy to clipboard operation
python copied to clipboard

feature: Add an option: `show_docstring_summary: false`

Open llucax opened this issue 2 years ago • 0 comments

Is your feature request related to a problem? Please describe.

Partially, the problem is it is hard to reuse modules or class documentation in high-level introductory docs written in mkdocs, at least when using Google style, because it mandates a summary line, which doesn't play well with the prose one usually expects from higher level docs.

Describe the solution you'd like

Add an option like show_docstring_summary that when set to false it will remove the summary line from the docstring description. The default should be true.

By setting show_docstring_description to false and show_docstring_summary to true it would also be possible to only show the summary.

Describe alternatives you've considered

I tried using mkdocs-macros to remove the summary, but then the sections in the docstring are not added to the ToC, so it is not a full solution.

Additional context

Discussion in Gitter: https://matrix.to/#/!xiyyvEeLIRaWsNQixq:gitter.im/$htcAJ1uZX3Af1I8Icn1xwFfqUm0ghhVBO1mwziuaSAo?via=gitter.im&via=matrix.org

llucax avatar Nov 15 '23 13:11 llucax