Decorators which alternate docstrings are ignored

[braniii]

Hi,

I've currently switched to mkdocs and I have have to say that this is an amazing project :)

But there are a few minor issues I did not manage to resolve on my own. I am using a simple self-written decorator from decorit which copies the Parameters section from a function to another. The function looks like the following:

def copy_doc_params(source: Callable) -> Callable:
    """Copy parameters from docstring source."""
    @beartype
    def wrapper_copy_doc(func: Callable) -> Callable:
        PARAMS_STRING = 'Parameters'
        doc_source = source.__doc__
        doc_func = func.__doc__
        if doc_source and doc_func and doc_source.find(PARAMS_STRING) != -1:
            # find last \n before keyphrase
            idx = doc_source[:doc_source.find(PARAMS_STRING)].rfind('\n')
            doc_params = doc_source[idx:]

            doc_params = doc_source[doc_source.find(PARAMS_STRING):]
            func.__doc__ = '{0}\n\n{1}'.format(  # noqa: WPS125
                doc_func.rstrip(),  # ensure that doc_func ends on empty line
                doc_params,
            )
        return func
    return wrapper_copy_doc

def func(a):
    """Function func.

    Parameters
    -----------------
    a : int
        Variable with name a.

    """
    pass

@copy_docs_params(func)
def gunc(a):
    """Function gunc."""
    pass

print(func.__name__, func.__doc__)
print(gunc.__name__, gunc.__doc__)

Printing the names, the docstring is copied as expected. But using it with mkdocs, it shows me only the original docstring of gunc. Including functools.wrap did not change the result.

Thank you for your help. Best, Daniel

[pawamoy]

Hi, thanks :heart: !

Are you sure you're using pytkdocs, through the mkdocstriings-python-legacy handler? The behavior you witness would make perfect sense if you're using the mkdocstrings-python handler, which only visits the AST and does not inspect code loaded in memory.

[braniii]

Thanks for your reply and I've confused the repos, so you are right! I am using the new python handler. Should I create a new issue at the correct repo, or is it a know issue?

[pawamoy]

It is not an issue per se, but the way to make it work is not documented yet (I'm working on it) :)

[pawamoy]

We now have a small how-to on how to support custom decorators: https://mkdocstrings.github.io/griffe/guide/users/how-to/support-decorators/.

[braniii]

Thank you so much for your time and effort :)