-
-
Notifications
You must be signed in to change notification settings - Fork 18
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
Comments
But that section is about "Parameters" which your example does not have. Does it work if you put that reference inside "Parameters" section? |
No it does not. I encountered problems with both cases. |
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) |
And that works if you don't use sphinx-astropy? I never knew you could reference a variable. |
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 |
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! |
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) |
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. |
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. |
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:
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.
The text was updated successfully, but these errors were encountered: