pytkdocs

pytkdocs copied to clipboard

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.

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:

Yay cool! I'll be patient. 🤓🍿