sphinx-doc / sphinx-doc/sphinx

Improve autodata docstring detection

Open
#6,495 13 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc type:enhancement
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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.