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! |
Hey, I am new to open source. Can I be assigned this project? Can someone guide me on how to get started? |
PRs that reduce the number of warnings are welcome. Instructions for one workflow are at the top of the issue. Try to make some progress and ask if you get stuck. |
Hello, I am new to open source, can I also be assigned to this project? and it would be great if some guidance can be provided about this issue and how to go forward with it. Thanks. |
@SiddheshBangar we do not assign issues. PRs that reduce the number of warnings are welcome. Instructions for one workflow are at the top of the issue. Try to make some progress and ask if you get stuck. |
Sorry sir @mattip, I am just confused, to exactly what should I look upon, I tried figuring it out but still don't get it. |
Hi @SiddheshBangar, I would suggest you first build the documentation by following this guide; it will help you to see how we use If you have problems re-creating the workflow, please let us know what you tried and what happened so that we can help you out! |
Hi, I wanted to make some small contributions to this and have picked out the errors:
in the resulting documentation build log file. I was looking for where to edit the docstrings of these functions and ended up finding |
Hi, @jon-deng. Did you rebuild NumPy before building the docs again? Just the docs rebuild will only reflect changes in |
Hi @Mukulikaa. I did run |
No, I think you are doing it right. I'll try to recreate this locally and try a few things. Meanwhile, feel free to open a draft PR of your changes if you want :) |
I figured out the issue with the docs not appearing. When I called |
There are 188 of these remaining (full list in the details below), of which ~60 is due to `size` instead of ``size``,
Edit: Since then I've learned that these linking issues should be resolved without doubling up on the backticks on parameters, and thus writing output... [100%] user/whatisnumpy <\details> |
@bsipocz Good to know! Please ping me if you come across other issues that seem suitable for a sprint. (We don't use the |
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: