-
-
Notifications
You must be signed in to change notification settings - Fork 10.3k
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
DOC: missing references when using -n in sphinx-build #13114
Comments
I would like to contribute to this , I am just confused about what exactly to look upon |
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 |
I will like to contribute to this |
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:
which is due to a typo (should be |
I'd also like to work on this issue and have the same question as mentioned by @nicholas-castro. Please kindly guide, @mattip |
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 @parulagg27 please coordinate with @nicholas-castro so that your work does not overlap. |
Note that it is sufficient to set an environment variable |
This is probably not fixed completely. It would be good if someone could try and paste the current status here. |
Here's the current status (generated from deb7943 on 5/4/20 using @mattip's workflow from the first comment): Summary: 792 total warnings Full log of link warnings
copying static files... ... done |
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. There's a couple of types of solutions:
tl;dr the "this is not a reference" is easy to fix, the other part requires knowledge of Sphinx and Numpydoc. |
I would like to contribute to this issue. Is someone working on this now? |
@takanori-pskq I don't think so. Please dive in, help is very welcome! |
Reducing 3 warnings (ref: numpygh-13114)
Corrected `lib.index_tricks.RClass` to `r_` instead of adding docstring of `RClass`. Reducing 2 warnings (numpygh-13114).
Reducing 3 warnings (ref: gh-13114) Co-authored-by: Matti Picus <matti.picus@gmail.com>
The python module ``distutils`` was removed in latest version (3.12), so the document of ``distutils`` does not exist. Reduced 4 reference warnings (see numpygh-13114). [skip cirrus] [skip azp] [skip actions]
The python module ``distutils`` was removed in latest version (3.12), so the document of ``distutils`` does not exist. Reduced 4 reference warnings (see numpygh-13114). [skip cirrus] [skip azp] [skip actions]
The python module ``distutils`` was removed in latest version (3.12), so the document of ``distutils`` does not exist. Reduced 4 reference warnings (see gh-13114). [skip cirrus] [skip azp] [skip actions]
ref: numpygh-13114 [skip cirrus] [skip azp] [skip actions]
ref: numpygh-13114 [skip cirrus] [skip azp] [skip actions]
ref: numpygh-13114 [skip cirrus] [skip azp] [skip actions]
After #25939 we are down to 30 warnings, thanks to all who contributed fixes especially @F3eQnxN3RriK. The remaining warnings:
remaining warnings>
|
Fixed the first one in the list at numpy#13114 (comment). [skip cirrus] [skip azp] [skip actions]
Hmm, the 2.0 release notes have new warnings too: new warnings
|
Set module of ``MaskedArray`` to ``numpy.ma`` because ``numpy.ma.core.MaskedArray`` is an internal alias not documented. ref: numpygh-13114 [skip cirrus] [skip azp] [skip actions]
Set module of ``MaskedArray`` to ``numpy.ma`` because ``numpy.ma.core.MaskedArray`` is an internal alias not documented. ref: numpygh-13114 [skip cirrus] [skip azp] [skip actions]
Closing, we now fail the doc build on warnings. Thanks to all who contributed to getting this long-standing issue fixed. |
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 theALLSPHINXOPTS
in theMakefile and add
-n`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.
The text was updated successfully, but these errors were encountered: