sphinx-doc / sphinx-doc/sphinx

Way to refresh python module after an autodoc

Open
#14,010 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Is your feature request related to a problem? Please describe.
It took me a while to figure that I was having issues with conflicting instances of get_annotations (or equivalent) due to the order in which they were executed, where I end up with weird states of ForwardRef or it can no longer evaluate with get_annotations(eval_str=True) or many other symptoms.

Describe the solution you'd like
Have a way to refresh the modules after autodoc has finished processing them for itself

Describe alternatives you've considered
Alternatively I could try to read the autodoc files afterwards, but I am concerned that it would have similar issues from the other side.

Edit: For now re-ordering does seem to work, but it requires reorganizing the doc structure so that the folder is alphabetically last

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 tracing Sphinx's autodoc module-processing flow and how it interacts with Python annotation evaluation, especially get_annotations and ForwardRef. Define how a post-autodoc refresh should work and verify that conflicting annotation states are cleared without requiring documentation reordering.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.