Inherited docstrings not rendering in many places

[jgostick]

It works fine when I do ctrl-i at the python command line in Spyder, but not from within the editor. I'm now hearing that is does not work on either in PyCharm or VSCode. I guess you've added some magic that works in spyder but is not standard protocol? Any suggestions?

[Chilipp]

Hey @jgostick ! Didn't you ask this before in #14? The command line in Spyder imports the packages, but the editors don't.

[jgostick]

This is a little different. Basically the docstrings only render in spyder, which seems like a serious limitation. Is there anything I can do to trick this into working?

[Chilipp]

Hey @jgostick. docrep definitely does not have any spyder- (or any other editor-) specific setup. docrep modifies the docstrings at runtime, so the only possibility to get this information is to actively import the library that uses docrep and I don't think any of the editors are doing this (even spyder does not work for me). But maybe I am not understanding you correct. Could you eventually paste a screenshot of how this works in the spyder editor?

My apologies for not being very helpful at the moment.

[jgostick]

I had a thought...how hard would it be to actually have docrep physical overwrite the files during the pip install phase? Is it possible to put a function or two in the setup.py file that would reaching into the source code and rewrite the docs?

[Chilipp]

hey @jgostick, interesting idea! I don't know how you would do this within setup.py as you probably don't want to modify your source files inplace and I don't know how to interfere with pip install or python setup.py install. For a conda package this would work as you can edit the build steps there.

However, I wonder what the downsides might be.

For instance, what about dynamic class creation?

def class_factory(some_parameter):

    @docstrings.dedent
    class A:
        """Some summary

        Parameters
        ----------
        %(base.parameters)s
        """

        a = some_parameter

        def __init__(self, *args, **kwargs):
            pass

    return A

A1 = class_factory(1)
A2 = class_factory(2)

(just an example, in real world this would be much more complicated and may even use the functionalities planned in #17). Is there a way to see, that the docstring of A should not be modified because it is dynamically generated?

and what about the case when the __doc__ attribute is set?

class A:
    __doc__ = docstrings.dedents("""
        Some summary

        Parameters
        ----------
        %(base.parameters)s
        """)

[jgostick]

Regarding changing the source files in-place, this is exactly what I'm proposing, which would work great for a true pip install from the pypi, but would be a problem for local installs, like if you downloaded the source code from github and did pip install -e package. That would be ok for a user, but would be a disaster if one of the devs did it and pushed their changed files, since we'd lose everything. I guess this idea a bit dead end, sorry.