sphinx-doc / sphinx-doc/sphinx
Decorator factory all documented as "alias of"
Nobody has claimed this yet.
- 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
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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