astropy / astropy/sphinx-automodapi

Resolve references when inheriting docstrings

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.