search

mkdocstrings / pytkdocs

Load Python objects documentation.
https://mkdocstrings.github.io/pytkdocs
ISC License
50 stars 32 forks source link

Allow to specify what exactly is a docstring for a given class #63

Closed yajo closed 1 month ago

yajo commented 4 years ago

Is your feature request related to a problem? Please describe. Yes, the problem is that some libraries use different attributes for docstrings than just __doc__.

For example, when using plumbum.cli.SwitchAttr, you define it like this. Now that object contains some data that is important to autodocument it:

>>> from copier.cli import CopierApp
>>> CopierApp.answers_file._switch_info.names
['a', 'answers-file']
>>> CopierApp.answers_file._switch_info.help
'Update using this path (relative to `destination_path`) to find the answers file'

Describe the solution you'd like I'd like to be able to explain to pytkdocs that the docstring for SwitchAttr objects is different than just __doc__. Or, at least, that it needs to obtain additional attributes from them (_switch_info) which I could override in the mkdocstrings template.

Describe alternatives you've considered I tried to override the attributes template, but it didn't have the necessary context information to obtain the data I needed.

Additional context Since I'm documenting CLI flags/switches, a very important thing I need to document is the --switch itself. That's not easy to get from current provided info.

pawamoy commented 3 years ago

Hey @Yajo, so sorry for having never answered to this :bow:

This won't happen in pytkdocs, but I'm working on a replacement. This tool replacing pytkdocs will parse the code instead of executing it. It will also make it easy to write extensions, to support third-party libraries such as plumbum. Taking your code example, it will be possible for an extension to visit the nodes corresponding to the assigned value (the cli.SwitchAttr instantiation) and set the docstring of the answers_file object using the value in the help parameter.

It's not ready yet, but I'm allocating time on it, so please be a bit more patient :pray: :sweat_smile:

yajo commented 3 years ago

Yay cool! I'll be patient. 🤓🍿

pawamoy commented 1 month ago

It's more than ready now, closing :slightly_smiling_face: Here are the docs to write extensions: https://mkdocstrings.github.io/griffe/guide/users/extending/.