sphinx-doc / sphinx-doc/sphinx

Decorator factory all documented as "alias of"

Open
#7,761 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc type:question
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug
I have a library module where functions have decorator versions generated for them via a factory function. The newly generated decorators have docstrings inherited from the base function. Factory code below, for context, see https://github.com/ZaxR/bulwark/blob/master/bulwark/decorators.py:

def decorator_factory(decorator_name, func):
    """Takes in a function and outputs a class that can be used as a decorator."""
    class decorator_name(BaseDecorator):
        __doc__ = func.__doc__
        check_func = staticmethod(func)

    return decorator_name

When I check the docstrings via the code, everything looks fine, but my Sphinx docs show each decorator's docstring as:

alias of bulwark.decorators.decorator_factory.<locals>.decorator_name

See https://bulwark.readthedocs.io/en/latest/_source/bulwark.decorators.html#bulwark.decorators.HasColumns .

To Reproduce
Steps to reproduce the behavior:

<Paste your command-line here which cause the problem>

$ git clone https://github.com/ZaxR/bulwark.git
$ cd bulwark
$ pip install -e ".[dev]"
$ cd docs
$ make html
$ # open _build/html/bulwark.decorators.html and see the descriptions

Expected behavior
I would like the factory-generated decorators to each show their docstring in the Sphinx docs.

Your project
https://github.com/ZaxR/bulwark

Screenshots
Example on readthedocs: https://bulwark.readthedocs.io/en/latest/_source/bulwark.decorators.html#bulwark.decorators.

Environment info

  • OS: [e.g. Unix/Linux/Mac/Win/other with version]
  • Python version: 3.8.2
  • Sphinx version: 2.4.4
  • Sphinx extensions: [
    'm2r',
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'sphinxcontrib.apidoc',
    ]
  • Extra tools: [Browser]

Additional context
Link above is to the readthedocs, but the same behavior is observed locally as well.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the issue by cloning bulwark, installing its development dependencies, and running make html from docs. Inspect the generated bulwark.decorators page and Sphinx's autodoc behavior; done when factory-generated decorators display their inherited docstrings instead of an "alias of" description.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.