astropy / astropy/sphinx-automodapi
Resolve references when inheriting docstrings
- Dominant language
- Python
- Stars
- 67
- Forks
- 48
- Avg merge
- 11h 52m
- Merged PRs (30d)
- 1
Description
Related to #156, but different--since automatic docstring inheritance isn't a normal "thing" in Python, Sphinx falls over a bit when this happens.
Normally when we write a docstring we don't have to write references _within the same module_ with a fully qualified name. For example, if I'm writing a docstring for a method in the `ConfigItem` class, I can refer to it just by:
```
`ConfigItem`
```
However, if I have a subclass of `ConfigItem` in a different module, and it inherits a docstring from one of `ConfigItem`'s methods that it otherwise overrides, it can no longer resolve that reference, because it looks for `ConfigItem` within the same module, not within the module that docstring originally came from. So we need to make autodoc somehow aware that this _can_ happen in some cases.
Contributor guide
No contributing guide indexed for this repository
Research direction
No files or tests are named. Start by reproducing the cross-module inherited-docstring example described in the issue and trace how Sphinx resolves references in the inherited text; done means references such as `ConfigItem` resolve using the module where the docstring originated.
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
- Mostly clear
- Newbie friendliness
- 35/100