Skip to content

Setting default_role breaks strict Numpydoc compatibility. #58

Description

@weaverba137

The Numpy Style Guide 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:

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.

See also the first note on Roles in the Sphinx documentation.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions