astropy / astropy/sphinx-automodapi

Remove auto-injection of references.txt files

Open
#65 0 comments 0 reactions 0 assignees View on GitHub
help wanted
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.