astropy / astropy/sphinx-automodapi
Remove auto-injection of references.txt files
- Dominant language
- Python
- Stars
- 67
- Forks
- 48
- Avg merge
- 11h 52m
- Merged PRs (30d)
- 1
Description
In automodsumm, we automatically check whether a ``references.txt`` file is present for the submodule being documented and if so injects it into every single docstring for that module:
https://github.com/astropy/sphinx-automodapi/blob/master/sphinx_automodapi/automodsumm.py#L635
This is actually not documented and also has an impact on performance since even small docstrings then have a full list of references to parse. In addition, people who read the docstrings in IPython won't actually see the references. I'd like to suggest that we remove this functionality from sphinx-automodapi and fix the astropy docstrings so that we explicitly put references in docstrings that need them rather than relying on this 'magic' behavior. I doubt any packages other than astropy use this since it isn't documented.
So for anyone who wants to help with this - install a developer version of sphinx-automodapi, remove the code that deals with the references.txt (linked above), then build the astropy docs and see which references break and fix them. Having had a quick look myself, a fair number of those references don't even really have to be references.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start in sphinx_automodapi/automodsumm.py around line 635 and remove the references.txt handling described in the issue. Install a developer version, build the Astropy documentation, and inspect which references break. Done means the automatic injection is gone and needed references are explicitly present in the affected docstrings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100