astropy / astropy/sphinx-astropy

Setting default_role breaks strict Numpydoc compatibility.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.