DOC: fix references in docs - #13104

Hey can I work on this?

Anyone is welcome to work on this. You should read up on building the documentation and then

• modify the code by adding -n as in the changes in this PR
• open a separate PR to fix some of the warnings about bad references. Choose a class of warnings (ma, polynomial, c-api.*.rst) and post a note here which class you are working on, to prevent duplicate work.
• read my top comment here for a suggested path to working through the warnings.

This pull request is still a work in progress.

can you get rid of that somehow @mattip?

We should merge this as-is, it improves the current situation. I opened #13114 with the content of the first comment for more work.

Merged, thanks @mattip

for the record, TravisCI did complete, it just failed to report its status back to this PR

it just failed to report its status back to this PR

I've observed that in a few places when using the official Draft Status mode for PRs.

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 run

(cd ..; pip install .); make clean; make html 2>&1 |tee /tmp/build.txt
less /tmp/build.txt

I followed the steps written, but I got error in conf.py

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/home/user/cop/opensource/numpy_new/env/lib/python3.7/site-packages/sphinx/config.py", line 319, in eval_config_file
    execfile_(filename, namespace)
  File "/home/user/cop/opensource/numpy_new/env/lib/python3.7/site-packages/sphinx/util/pycompat.py", line 81, in execfile_
    exec(code, _globals)
  File "/home/user/cop/opensource/numpy_new/numpy/doc/sphinxext/doc/conf.py", line 132, in <module>
    raise RuntimeError("Get the scipy-sphinx-theme first, "
RuntimeError: Get the scipy-sphinx-theme first, via git submodule init && git submodule update
 

I guess I know what the error is about. On line 132 in conf.py
Replacing

if not os.path.isdir(themedir):
     raise RuntimeError("Get the scipy-sphinx-theme first, "
                        "via git submodule init && git submodule update")

with this helps.

try:
    os.path.isdir(themedir)
except:
     raise RuntimeError("Get the scipy-sphinx-theme first, "
                        "via git submodule init && git submodule update")

The error here is supposed to guide you how to solve the problem: try running git submodule update --init