Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Clean up warnings in doc build #5610

Open
TomAugspurger opened this issue Nov 20, 2019 · 8 comments · Fixed by #8432
Open

Clean up warnings in doc build #5610

TomAugspurger opened this issue Nov 20, 2019 · 8 comments · Fixed by #8432
Labels
documentation Improve or add to documentation good first issue Clearly described and easy to accomplish. Good for beginners to the project.
Projects
Core maintenance

Comments

@TomAugspurger
Copy link
Member

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

/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
@TomAugspurger TomAugspurger added the documentation Improve or add to documentation label Nov 20, 2019
This was referenced Nov 20, 2019
Merged
Merged
@TomAugspurger TomAugspurger added this to Sorted Backlog in Core maintenance Nov 26, 2019
This was referenced Dec 3, 2019
Merged
Merged
@TomAugspurger TomAugspurger moved this from Sorted Backlog to In progress in Core maintenance Dec 17, 2019
@mrocklin mrocklin moved this from In progress to Backlog in Core maintenance Jan 7, 2020
@jsignell jsignell added good second issue Clearly described, educational, but less trivial than "good first issue". good first issue Clearly described and easy to accomplish. Good for beginners to the project. and removed good second issue Clearly described, educational, but less trivial than "good first issue". labels Mar 19, 2021
@jsignell
Copy link
Member

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

@jsignell jsignell mentioned this issue Mar 19, 2021
Merged
mesejo added a commit to mesejo/dask that referenced this issue Apr 4, 2021
@mesejo
Clean some of the warnings described in dask#5610
4b5af0e 
Fixes issues like:
* duplicate function documentation
* indentation in bullet list problem
* unknown target name
@mesejo
Copy link
Contributor

mesejo commented Apr 4, 2021

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 jsignell linked a pull request Apr 5, 2021 that will close this issue
Getting rid of more docs warnings #7426
Merged
2 tasks
@jsignell
Copy link
Member

jsignell commented Apr 5, 2021 •
edited

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 :)

@jsignell jsignell removed a link to a pull request Apr 5, 2021
Getting rid of more docs warnings #7426
Merged
2 tasks
@rajpratyush
Copy link

is this issue still open for work??

@jrbourbeau
Copy link
Member

This issue is still open. Feel free to contribute @rajpratyush

@boazmohar boazmohar mentioned this issue Nov 10, 2021
Merged
3 tasks
This was referenced Nov 30, 2021
Merged
Closed
@koverholt
Copy link
Member

I opened #8432 and dask/distributed#5549 to address the remaining build warnings. And I've enabled the option to treat build warnings as errors in those PRs.

@jrbourbeau
Copy link
Member

Re-opening as I think we still have a few warnings emitted during our documentation build. We should close this issue once we've enabled the "elevate warnings to errors" setting

@jrbourbeau jrbourbeau reopened this Feb 21, 2022
This was referenced Jan 23, 2023
Merged
Merged
@benrutter
Copy link
Contributor

I know this issue is pretty old now - is it still valid? Looks from building the docs locally like I don't get any errors?

Is the "elevate warnings to errors" aspect still relevant? In terms of building locally, this could be achieved with 'make html "SPHINXOPTS=-W"', but I'm guessing there are parts of cicd etc that need to do this instead potentially?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation Improve or add to documentation good first issue Clearly described and easy to accomplish. Good for beginners to the project.
Projects
Core maintenance
Backlog
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Fix docs build warnings koverholt/dask
7 participants
@koverholt @TomAugspurger @jsignell @mesejo @jrbourbeau @rajpratyush @benrutter