astropy / astropy/sphinx-astropy
Setting default_role breaks strict Numpydoc compatibility.
- Dominant language
- Python
- Stars
- 7
- Forks
- 19
- Avg merge
- 5h 41m
- Merged PRs (30d)
- 1
Description
[The Numpy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html#parameters) suggests the use of single backticks to refer to function parameters.
However, because sphinx-astropy (sphinx_astropy.conf.default_role) defines `default_role = 'obj'`, these are interpreted as objects rather than as (informal) references to function parameters.
For example, if I write:
```python
def rectangle(width, height=None):
"""Define a rectangle; `width` should be specified in degrees.
"""
if height is None:
height = width
return (width, height)
```
I'll get a warning like: `WARNING: py:obj reference target not found: width`.
This isn't documented in [the Astropy Documentation Guidelines](https://docs.astropy.org/en/latest/development/docguide.html#astropy-documentation-rules-and-guidelines).
See also the [first note on Roles](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#roles) in the Sphinx documentation.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start at sphinx_astropy.conf.default_role and reproduce the warning from the rectangle example using the Numpydoc single-backtick convention. Compare the behavior with the Astropy Documentation Guidelines and the linked Sphinx roles note. Done means the documented convention no longer produces an inappropriate unresolved-object warning, or the incompatibility is clearly documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100