Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Setting default_role breaks strict Numpydoc compatibility. #58

Open
weaverba137 opened this issue Mar 9, 2023 · 9 comments
Open

Setting default_role breaks strict Numpydoc compatibility. #58

weaverba137 opened this issue Mar 9, 2023 · 9 comments

Comments

@weaverba137
Copy link
Member

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.

@pllim
Copy link
Member

pllim commented Mar 9, 2023

But that section is about "Parameters" which your example does not have. Does it work if you put that reference inside "Parameters" section?

@weaverba137
Copy link
Member Author

No it does not. I encountered problems with both cases.

@weaverba137
Copy link
Member Author

If you like a more thorough test case would be:

def rectangle(width, height=None):
    """Define a rectangle; `width` should be specified in degrees.

    Parameters
    ----------
    width : float
        Width of the rectangle in degrees.
    height : float, optional
        Height of the rectangle. If not specified, `width` will be used.

    Returns
    -------
    tuple
        The desired rectangle.
    """
    if height is None:
        height = width
    return (width, height)

@pllim
Copy link
Member

pllim commented Mar 10, 2023

And that works if you don't use sphinx-astropy? I never knew you could reference a variable.

@weaverba137
Copy link
Member Author

Correct. I use Sphinx with Numpydoc, but without sphinx-astropy, all the time in other projects, and never see a warning about this. Specifically we do not set default_role, rather than setting it to some other value.

@pllim
Copy link
Member

pllim commented Mar 10, 2023

Well, I really don't know when anyone would have time to fix this, especially given the exploration of a completely different theme at astropy/astropy#14477 . The easiest workaround, if you have not found a better one already, is to use double backticks to avoid the ref linking. We apologize for any inconvenience caused!

@bsipocz
Copy link
Member

bsipocz commented Mar 10, 2023

I don't see what it has to do with the theme. But the problem is certainly well known but not clear anyone will have the time to fix it, we all very much used to double ticking everything that are not links. (and recently there has been some bugs in this on numpyland, too)

@pllim
Copy link
Member

pllim commented Mar 10, 2023

I don't think we'll be using anything from here anymore if we switch to pydata-sphinx-theme? Anyways, I am not 100% sure.

@bsipocz
Copy link
Member

bsipocz commented Mar 10, 2023

automodapi may still need some of these configs, let alone what core does has little to do with e.g. the coordinated packages.

Either case, using double backticks is the suitable workaround, or overriding the config item for the given package, but even then it may not work as expected.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants