search

Chilipp / docrep

A Python Module for intelligent reuse of docstrings
Apache License 2.0
30 stars 4 forks source link

Insert generated text into docstring? #14

Closed jgostick closed 5 years ago

jgostick commented 5 years ago

This is more a feature request than an issue...

I would like to inject some programmatically generated text into my docstrings, and based on the awesomeness of docrep, I"m sure you know how to do it.

For instance, consider the following docstring:

"""
This is a function docstring

"{0}"

More docstring
""".format(('insert this'))

This is a valid python string and the text will be inserted at the {0} location. But in spyder and sphinx, this does not work. Since docrep is able to inject text that DOES work with spyder and sphinx, I wonder if you have any suggestions?

BTW, my actually use case is to inject a generated table of functions into the docstring for a module init, so that an up-to-date list of all functions can be displayed in spyder / sphinx without me having to manually maintain the list as functions are added/removed/renamed etc.

Chilipp commented 5 years ago

hi @jgostick ! Hmm, I think I know what you mean. You want, while typing in the Spyder editor window and using the code introspection, that the formatted docstring is shown in the help explorer. Do I get you right?

However, this does not work with docrep as you can see in the screenshot below

image

Here I use the code introspection on the keys method to show it's docstring in spyders help. The keys method thereby uses some docstring parts from another method and they are inserted using the dostrings.dedent decorator.

However, spyder does not really import the module to get the docstring from the object. Instead it uses some other functionality in order to avoid large loading times. Hence, the decorator @docstrings.dedent in the above screenshot is not executed and spyder does not know that the docstring of keys actually looks different.

Within a normal sphinx documentation, this is different, since the autodoc extension imports the modules that are to be documented.

Therefore, unfortunately, I don't have any idea about how to use your formatted docstring within spyder.

jgostick commented 5 years ago

thanks for your time!

Chilipp commented 5 years ago

You're welcome. Sorry I could not help.

Good luck!