Repository navigation
DOC: missing references when using -n in sphinx-build #13114
Description
Started in #13104, turned into a tracking issue here.
Turning on -n in sphinx-build results in over 1000 warnings about bad references in docs. Trying to break these down with various grep statements, it seems about 200 are from numpy.ma, about 150 from polynomial and about 150 from c:type. That is under half of the WARNINGS.
My workflow is to cd to the , My workflow is to set an environment variable SPHINXOPTS='-n' then rundoc directory, modify the ALLSPHINXOPTS in the Makefile and add -n`
(cd ..; pip install .); make clean; make html 2>&1 |tee /tmp/build.txt
less /tmp/build.txt
and look for the most common lines. Unfortunately this takes quite a while.
Anyone who wishes to contribute can issue PRs, preferably in chunks that address one class of failure. #13104 gives an idea of the changes needed.
Activity
devayanipowar commentedon Mar 13, 2019
I would like to contribute to this , I am just confused about what exactly to look upon
mattip commentedon Mar 13, 2019
did you try to follow the steps above? Then you should look at the lines of /tmp/build.txt that have the WARNING in them
Jenniline commentedon Mar 14, 2019
I will like to contribute to this
[-]DOC: misssing referencese when using -n in sphinx-build[/-][+]DOC: misssing references when using -n in sphinx-build[/+]nicholas-castro commentedon Mar 22, 2019
Hi, I'm working on this for the warnings that are generated for functions in the polynomial submodule. This is my first time working with Sphinx, so I have a rather basic question -- which docstring should I edit? Take, for example, the following error:
/usr/lib/python3.7/site-packages/numpy/polynomial/chebyshev.py:docstring of numpy.polynomial.chebyshev.chebdiv:29: WARNING: py:obj reference target not found: chemulxwhich is due to a typo (should be
chebmulx). The file at/usr/lib/python3.7/site-packages/numpy/polynomial/chebyshev.pyis read-only, so I cannot save changes. However, if I edit my local copy of the repository innumpy/polynomial/chebyshev.pythe changes don't seem to be reflected when I re-build the docs. If you could point me on the right path I'd be really grateful, sorry for the basic question.parulagg27 commentedon Apr 6, 2019
I'd also like to work on this issue and have the same question as mentioned by @nicholas-castro. Please kindly guide, @mattip
mattip commentedon Apr 7, 2019
You need to re-install numpy into the python that is building the documentation, so that sphinx can pick up the changes. That is why there is a
pip install .in what I wrote above.@parulagg27 please coordinate with @nicholas-castro so that your work does not overlap.
[-]DOC: misssing references when using -n in sphinx-build[/-][+]DOC: missing references when using -n in sphinx-build[/+]mattip commentedon Jun 10, 2019
Note that it is sufficient to set an environment variable
SPHINXOPTS='-n'and then generate documentation, no need to edit theMakefileanymore.rgommers commentedon May 4, 2020
This is probably not fixed completely. It would be good if someone could try and paste the current status here.
rossbar commentedon May 5, 2020
Here's the current status (generated from deb7943 on 5/4/20 using @mattip's workflow from the first comment):
Summary: 792 total warnings
* ~90 from
numpy.madocstrings* ~120 from
numpy.polynomialdocstringsFull log of link warnings
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 792 warnings.
make: *** [Makefile:179: html-build] Error 1
rgommers commentedon May 5, 2020
Thanks @rossbar. Okay, there's still some low-hanging fruit here. Let's leave it as a "good first issue".
For clarity: the issue is that there are references (things with single backticks around them, i.e.
`somename`) that do not reference another function or object that can be found.There's a couple of types of solutions:
`True`should be``True``(or simply without backticks).numpy.ma.argsorthas a reference tolexsortin itsSee Also; there's nonumpy.ma.lexsortso this meansnumpy.lexsort. On reflection, that link should be valid (as are many others), there may be something wrong with the lookup mechanism. IIRC the rules are that first the current scope is checked for a matching name, and then the next scope up. In SciPy this works correctly, in NumPy it does seem to - some.. currentmodule::'s set incorrectly perhaps?tl;dr the "this is not a reference" is easy to fix, the other part requires knowledge of Sphinx and Numpydoc.
takanori-pskq commentedon May 12, 2020
I would like to contribute to this issue. Is someone working on this now?
27 remaining items
rossbar commentedon Feb 25, 2023
Note that this was only partially closed by #23278, reopening for visibility.
drammock commentedon Apr 28, 2023
@mattip I took a quick look at this issue. Perhaps this is already common knowledge among the dev team, but one big problem I see is the use of single-backtick surrounds when referring to parameter names in docstrings (i.e., what @bsipocz alluded to above).
To fully elucidate (for those not familiar with the issue): sphinx will try to parse single-backtick-surrounded expressions as cross-references to API entries in the default domain, and if it fails it will fall back to treating single-backticks like single-asterisks (i.e., markup for emphasis/italicization). Example:
Here "buffer", "shape", "dtype", and "order" are all class params and all have single-backtick surround in the docstring source, but "shape" and "dtype" get different formatting because they're (mistakenly) identified as references to
np.shapeandnp.dtype.Options to fix this are:
primary_domain=Noneinconf.py. Then the single-backticks can be left alone (should render as italics), but any intentional API cross-refs need to be prefixed with:py:func:,:py:meth:, or:py:class:in order to still work.Needless to say any of these is a lot of work, but there might be ways to at least partially automate it. I'd be willing to give it a shot if I had buy-in on which approach was acceptable (if any of them are). It would be nice to get the docs to a state where
nitpickycould be enabled in the CIs, so that any new xref errors could be detected at PR time.seberg commentedon Apr 28, 2023
@rossbar do you think there is any problem with
numpydochistorically prescribing/suggesting the use of backticks for parameters? I.e. changing numpydoc (or its style guide) to rather suggest the_param_spelling?(Unless we can actually manage numpy-doc to link to the parameter, but that seems rather unlikely)
drammock commentedon Apr 28, 2023
Pretty sure this would at least be very very difficult; it's sphinx that does the linking and AFAIK sphinx doesn't create targets for every function/method/class parameter.
bsipocz commentedon Apr 28, 2023
I recall that Ross had a workaround in mind, and certainly showed me once that this is a bug rather than a feature. Either case, I would love if we could get to the bottom of it with a solution during the summit!
rossbar commentedon Apr 28, 2023
Yeah I still strongly advocate for fixing this upstream in numpydoc - that way, the fix will apply to all libraries that use the numpydoc extension for their docstrings. As I've proposed elsewhere, I think there's a relatively straightforward path to try. It looks something like this:
:emph:to resolve the nit-picky links issue.If I were to attempt solving this problem, this is where I'd start!
DOC: Fix references to `AxisError` in docstrings (#23918)
DOC: Removed references to ``distutils`` in simd document (#25783)
mattip commentedon Mar 6, 2024
After #25939 we are down to 30 warnings, thanks to all who contributed fixes especially @F3eQnxN3RriK. The remaining warnings:
PyArrayDescras a parameter type seems to fail here and in the other similar declarations (9 warnings)FILE,size_tandPyHeapTypeObjectare not valid refs (13 warnings)collections.abc.Mappingfunctions (4 warnings)numpy.ma.core.MaskedArray(3 warnings), has it moved?pandas.DataFrame.to_numpyreference (1 warning)remaining warnings>
mattip commentedon Mar 6, 2024
Hmm, the 2.0 release notes have new warnings too:
new warnings
DOC: Fix module setting of ``MaskedArray``
mattip commentedon Dec 26, 2024
Closing, we now fail the doc build on warnings. Thanks to all who contributed to getting this long-standing issue fixed.