sphinx-doc / sphinx-doc/sphinx
Improve autodata docstring detection
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Currently, if a variable (eg. a data dict MY_VARIABLE) is imported from a submodule to a parent module, and that an "autodata" pointing to the parent module's MY_VARIABLE is added to documentation, the initial MY_VARIABLE's docstrings (eg. "#: stuffs" is lost. It doesn't seem possible to add this docstring near the "from submodule import MY_VARIABLE).
Autodata "annotation" can be used to workaround this, but in this case the repr() of the variable (that I wanted to be in docs) doesn't appear anymore.
It would be nice for sphinx to follow imports and find the docstring of imported variables, or that it uses a force-injected "doc" one would put in such variables (I tried, it didn't work), or that there is a way to force a display of the repr() of a variable.
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
Start by reproducing the imported MY_VARIABLE case described in the issue, including an autodata entry for the parent module and the original #: docstring. Trace how autodata handles imported variables and repr() output; done requires an agreed behavior that preserves the variable documentation and/or representation, followed by regression coverage.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 32/100