Clean up warnings in doc build

[TomAugspurger]

Right now our doc build has many warnings. This makes it hard to catch newly introduced errors in the doc build. Sphinx has an option to elevate warnings to errors.

In the details, I've included some warnings from a recent local build

Details

/Users/taugspurger/miniconda3/envs/dask-dev/lib/python3.7/site-packages/numpydoc/docscrape.py:377: UserWarning: Unknown section Paramters in the docstring of None in None.
  warn(msg)
/Users/taugspurger/miniconda3/envs/dask-dev/lib/python3.7/site-packages/numpydoc/docscrape.py:377: UserWarning: Unknown section Paramters in the docstring of <function make_people at 0x1053d3c80> in /Users/taugspurger/sandbox/dask/dask/datasets.py.
  warn(msg)
/Users/taugspurger/miniconda3/envs/dask-dev/lib/python3.7/importlib/_bootstrap.py:219: RuntimeWarning: numpy.ufunc size changed, may indicate binary incompatibility. Expected 192 from C header, got 216 from PyObject
  return f(*args, **kwds)
/Users/taugspurger/miniconda3/envs/dask-dev/lib/python3.7/importlib/_bootstrap.py:219: RuntimeWarning: numpy.ufunc size changed, may indicate binary incompatibility. Expected 192 from C header, got 216 from PyObject
  return f(*args, **kwds)
/Users/taugspurger/miniconda3/envs/dask-dev/lib/python3.7/importlib/_bootstrap.py:219: RuntimeWarning: numpy.ufunc size changed, may indicate binary incompatibility. Expected 192 from C header, got 216 from PyObject
  return f(*args, **kwds)
/Users/taugspurger/sandbox/dask/dask/array/core.py:docstring of dask.array.from_array:16: WARNING: Unexpected indentation.
/Users/taugspurger/sandbox/dask/dask/array/core.py:docstring of dask.array.from_array:17: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/taugspurger/sandbox/dask/dask/array/routines.py:docstring of dask.array.apply_along_axis:13: WARNING: Unexpected section title.

Parameters
__________
/Users/taugspurger/sandbox/dask/dask/array/creation.py:docstring of dask.array.indices:26: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/taugspurger/sandbox/dask/dask/array/percentile.py:docstring of dask.array.percentile:19: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/taugspurger/sandbox/dask/dask/array/core.py:docstring of dask.array.from_array:16: WARNING: Unexpected indentation.
/Users/taugspurger/sandbox/dask/dask/array/core.py:docstring of dask.array.from_array:17: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/taugspurger/sandbox/dask/dask/array/core.py:docstring of dask.array.to_npy_stack:26: WARNING: Inline substitution_reference start-string without end-string.
/Users/taugspurger/sandbox/dask/dask/array/core.py:docstring of dask.array.to_npy_stack:26: WARNING: Inline substitution_reference start-string without end-string.
/Users/taugspurger/sandbox/dask/dask/array/core.py:docstring of dask.array.to_npy_stack:26: WARNING: Inline substitution_reference start-string without end-string.
/Users/taugspurger/sandbox/dask/dask/array/core.py:docstring of dask.array.to_npy_stack:26: WARNING: Inline substitution_reference start-string without end-string.
/Users/taugspurger/sandbox/dask/dask/array/core.py:docstring of dask.array.Array.moment:44: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/Users/taugspurger/sandbox/dask/dask/array/core.py:docstring of dask.array.Array.vindex:12: WARNING: Unknown target name: "1".
/Users/taugspurger/sandbox/dask/docs/source/array-creation.rst:221: WARNING: Duplicate explicit target name: "zarr".
/Users/taugspurger/sandbox/dask/docs/source/custom-collections.rst:46: WARNING: Unexpected section title.

Returns
-------
/Users/taugspurger/sandbox/dask/docs/source/custom-collections.rst:58: WARNING: Unexpected section title.

Returns
-------
/Users/taugspurger/sandbox/dask/docs/source/custom-collections.rst:79: WARNING: Unexpected section title.

Parameters
----------
/Users/taugspurger/sandbox/dask/docs/source/custom-collections.rst:91: WARNING: Unexpected section title.

Returns
-------
/Users/taugspurger/sandbox/dask/docs/source/custom-collections.rst:116: WARNING: Unexpected section title.

Returns
-------
/Users/taugspurger/sandbox/dask/docs/source/custom-collections.rst:139: WARNING: Unexpected section title.

Returns
-------
WARNING: failed to import to_dask_array
WARNING: failed to import to_delayed
/Users/taugspurger/sandbox/dask/dask/dataframe/core.py:docstring of dask.dataframe.DataFrame.merge:17: WARNING: Unexpected indentation.
/Users/taugspurger/sandbox/dask/dask/dataframe/core.py:docstring of dask.dataframe.DataFrame.merge:19: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/taugspurger/sandbox/dask/dask/dataframe/core.py:docstring of dask.dataframe.DataFrame.where:141: WARNING: Duplicate explicit target name: "user guide".
/Users/taugspurger/sandbox/dask/dask/dataframe/core.py:docstring of dask.dataframe.Series.where:141: WARNING: Duplicate explicit target name: "user guide".
/Users/taugspurger/sandbox/dask/dask/dataframe/core.py:docstring of dask.dataframe.Series.where:141: WARNING: Duplicate explicit target name: "user guide".
/Users/taugspurger/sandbox/dask/dask/dataframe/io/parquet/core.py:docstring of dask.dataframe.read_parquet:25: WARNING: Definition list ends without a blank line; unexpected unindent.
WARNING: autodoc: failed to import function 'make_meta' from module 'utils'; the following exception was raised:
No module named 'utils'
/Users/taugspurger/sandbox/dask/docs/source/institutional-faq.rst:158: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/taugspurger/sandbox/dask/docs/source/institutional-faq.rst:160: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/taugspurger/sandbox/dask/docs/source/institutional-faq.rst:161: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/taugspurger/sandbox/dask/docs/source/institutional-faq.rst:171: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/taugspurger/sandbox/dask/docs/source/institutional-faq.rst:174: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/taugspurger/sandbox/dask/docs/source/remote-data-services.rst:262: WARNING: Explicit markup ends without a blank line; unexpected unindent.
WARNING: duplicate object description of distributed.Client.register_worker_plugin, other instance in futures, use :noindex: for one of them
/Users/taugspurger/sandbox/distributed/distributed/deploy/ssh.py:docstring of distributed.deploy.ssh.SSHCluster:30: WARNING: Unexpected indentation.
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/taugspurger/sandbox/dask/docs/source/phases-of-computation.rst: WARNING: document isn't included in any toctree
/Users/taugspurger/sandbox/dask/docs/source/scheduler-choice.rst: WARNING: document isn't included in any toctree
/Users/taugspurger/sandbox/dask/docs/source/scheduler-overview.rst: WARNING: document isn't included in any toctree
/Users/taugspurger/sandbox/dask/docs/source/scheduling-policy.rst: WARNING: document isn't included in any toctree
/Users/taugspurger/sandbox/dask/docs/source/shared.rst: WARNING: document isn't included in any toctree

/Users/taugspurger/miniconda3/envs/dask-dev/lib/python3.7/site-packages/dask_sphinx_theme/layout.html:22: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a <script> tag directly in your theme instead.
  <ul>
/Users/taugspurger/sandbox/dask/docs/source/dataframe-create.rst:10: WARNING: unknown document: dataframe-overview
/Users/taugspurger/sandbox/distributed/distributed/client.py:docstring of distributed.Client.compute:44: WARNING: unknown document: resources
/Users/taugspurger/sandbox/distributed/distributed/client.py:docstring of distributed.Client.compute:51: WARNING: unknown document: actors
/Users/taugspurger/sandbox/distributed/distributed/client.py:docstring of distributed.Client.map:40: WARNING: unknown document: resources
/Users/taugspurger/sandbox/distributed/distributed/client.py:docstring of distributed.Client.map:46: WARNING: unknown document: actors
/Users/taugspurger/sandbox/distributed/distributed/client.py:docstring of distributed.Client.persist:38: WARNING: unknown document: resources
/Users/taugspurger/sandbox/distributed/distributed/client.py:docstring of distributed.Client.persist:45: WARNING: unknown document: actors
/Users/taugspurger/sandbox/distributed/distributed/client.py:docstring of distributed.Client.submit:42: WARNING: unknown document: resources
/Users/taugspurger/sandbox/distributed/distributed/client.py:docstring of distributed.Client.submit:47: WARNING: unknown document: actors
/Users/taugspurger/sandbox/dask/docs/source/setup/custom-startup.rst:30: WARNING: unknown document: plugins

copying static files... done
copying extra files... /Users/taugspurger/miniconda3/envs/dask-dev/lib/python3.7/site-packages/sphinx_rtd_theme/search.html:20: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a <script> tag directly in your theme instead.
  {{ super() }}
WARNING: html_extra_path entry '/Users/taugspurger/sandbox/dask/docs/source/index.html' does not exist

[jsignell]

Just wanted to drop a note here that there are still many docs warnings https://readthedocs.org/api/v2/build/13290377.txt for example

[mesejo]

There are a few warnings, such as:

/home/docs/checkouts/readthedocs.org/user_builds/dask/checkouts/7419/docs/source/scheduler-overview.rst: WARNING: document isn't included in any toctree
/home/docs/checkouts/readthedocs.org/user_builds/dask/checkouts/7419/docs/source/scheduling-policy.rst: WARNING: document isn't included in any toctree
/home/docs/checkouts/readthedocs.org/user_builds/dask/checkouts/7419/docs/source/shared.rst: WARNING: document isn't included in any toctree

see https://readthedocs.org/api/v2/build/13290827.txt

In which toctree, should these .rst files be included?

[jsignell]

I think I've addressed those in #7426 @mesejo, sorry I forgot to link back to this issue. There are still some more to tackle though :)