Silence sphinx warnings #4286

keewis · 2020-07-29T20:48:17Z

This prepares our docstrings for the improvements to napoleon in the upcoming sphinx release (~~I'm not aware of a fixed date, though~~ it's going to be released around Aug 08, so in about a week from now). napoleon now has a stricter syntax for parameter type specs with napoleon_use_param = True, which allows it to link to all referenced types.

We can't do much about the inherited docstrings, though, so we'd probably have to fix that upstream.

works towards closing Hundreds of Sphinx errors #3370
Passes isort . && black . && mypy . && flake8
User visible changes (including notable bug fixes) are documented in whats-new.rst
New functions/methods are listed in api.rst

…unctions

keewis · 2020-07-31T21:04:09Z

@spencerkclark, while working on this PR I got a warning about CFTimeOffset not being linkable in CFTimeIndex.floor / ceil / round. Looking through the code, I can only find BaseCFTimeOffset, there's no CFTimeOffset class (maybe we should rename that base class?).

Anyway, I don't think any of those is part of the public api? If the methods on CFTimeIndex are public, I think we either shouldn't reference these classes or make them public (or add a glossary term to define what CFTimeOffset means).

spencerkclark · 2020-07-31T21:21:16Z

Anyway, I don't think any of those is part of the public api? If the methods on CFTimeIndex are public, I think we either shouldn't reference these classes or make them public (or add a glossary term to define what CFTimeOffset means).

Thanks for catching this; I agree they are not currently public API, so let's remove the references to them in docstrings of public functions. And it's true, I think CFTimeOffset would be a better name for the base class, but we can wait until later to act on that.

max-sixty · 2020-08-06T15:54:39Z

Thanks a lot @keewis !

because that will separate combined parameter docs by duplicating the description

dcherian · 2020-08-12T19:57:06Z

@keewis: this is great!

keewis · 2020-08-12T20:09:50Z

doc/terminology.rst

+    name
+        The names of dimensions, coordinates, DataArray objects and data
+        variables can be anything as long as they are :term:`hashable`. However,
+        it is preferred to use :py:class:`str` typed names.
+
+    scalar
+        By definition, a scalar is not :term:`array_like`. That means that,
+        e.g., :py:class:`int`, :py:class:`float`, and :py:class:`str` values are
+        "scalar" while :py:class:`list` or :py:class:`tuple` are not.


these definitely need a review, I'm not quite sure these are easy to understand

keewis · 2020-08-12T23:00:10Z

most of the remaining broken links are due to other sections (mostly the See Also section). To fix that, napoleon has to first add support for preprocessing those sections.

shoyer

This is a great cleanup, thank you!

shoyer · 2020-08-13T06:27:18Z

doc/terminology.rst

+        it is preferred to use :py:class:`str` typed names.
+
+    scalar
+        By definition, a scalar is not :term:`array_like`. That means that,


Should "array like" also be defined somewhere in order for a link to work? Or does this just add some sort of formatting?

My definition of a "scalar" might be anything that isn't an array and that when converted into a NumPy array would have 0 dimensions.

NumPy defines "array like" as anything that can be converted into an array. So that definition includes scalar values.

right now we're linking to numpy's definition of the term (thanks to intersphinx), so defining it on our own might not be necessary.

I updated the definition, is it better now?

doc/terminology.rst

Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>

dcherian · 2020-08-14T15:12:18Z

doc/terminology.rst

+        variables can be anything as long as they are :term:`hashable`. However,
+        it is preferred to use :py:class:`str` typed names.
+
+    scalar


Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>

doc/dask.rst

dcherian · 2020-08-19T14:59:39Z

Thanks @keewis. Great work!

max-sixty · 2020-08-19T15:22:21Z

A Napoleonic PR! (pun intended)

keewis added 18 commits July 26, 2020 12:35

generate documentation for the a few missing CFTimeIndex attributes

2d617e7

properly use continuation lines

edae8bc

add a missing quote

c9c6a95

delete the note about the removed auto_combine

b7794bd

replace auto_combine with combine_by_coords

66ed0e0

set the current module in dask.rst

04b9cc8

fix some links in whats-new.rst and generate doc pages for the plot f…

d56a9f5

…unctions

add the new CFTimeIndex methods to api-hidden

8bb0a47

don't link to CFTimeIndex.__repr__

3a8f318

don't try to link to the datetime accessor

d997769

fix a few more docstrings

baab87b

remove the non-html options (which are rarely used?) and silence flake8

f174f76

add type aliases

1f36ca4

map ComplexWarning to numpy.ComplexWarning

b76cb75

fix more docstrings

05e204e

add some missing methods and properties to api-hidden

66caef9

more aliases

a7daa90

fix a few more docstrings

3881799

properly reference ... (Ellipsis)

3fdab8f

keewis added 6 commits August 1, 2020 00:12

update the docstrings of dataset

b67c280

update the docstrings of DataArray

09576d3

remove the references to CFTimeOffset

4c797eb

fix a lot more docstrings

bf1c433

fix even more docstrings

4a49002

Merge branch 'master' into silence-sphinx-warnings

c5d1a24

remove a few more workarounds for a sphinx bug

f8245b8

keewis mentioned this pull request Aug 8, 2020

pin sphinx #4326

Merged

keewis added 8 commits August 12, 2020 15:20

mark a parameter as optional

28ae240

more docstrings

836cf80

use code blocks instead of literal blocks with doctest lines

939793c

add back a removed colon

a0230b6

convert the glossary page to a sphinx glossary

e000be1

add term descriptions for names and scalars

f3546fc

preprocess types but don't use :param:

74086d7

because that will separate combined parameter docs by duplicating the description

link to the terms

9a74495

don't try to link to the repr method

f1731ec

keewis commented Aug 12, 2020

View reviewed changes

shoyer approved these changes Aug 13, 2020

View reviewed changes

update the definition of scalar according to the review

f299eec

max-sixty reviewed Aug 13, 2020

View reviewed changes

doc/terminology.rst Outdated Show resolved Hide resolved

max-sixty reviewed Aug 13, 2020

View reviewed changes

doc/terminology.rst Outdated Show resolved Hide resolved

Update doc/terminology.rst

0f6641b

Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>

dcherian reviewed Aug 14, 2020

View reviewed changes

dcherian approved these changes Aug 14, 2020

View reviewed changes

keewis and others added 6 commits August 14, 2020 22:30

Update doc/terminology.rst

055b0ba

Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>

Merge branch 'master' into silence-sphinx-warnings

1e10430

Merge branch 'master' into silence-sphinx-warnings

b865041

Merge branch 'master' into silence-sphinx-warnings

292d7e4

fix a bad merge

bb51167

fix the docstring of cftime_range

419dd01

keewis commented Aug 19, 2020

View reviewed changes

doc/dask.rst Show resolved Hide resolved

dcherian merged commit d9ebcaf into pydata:master Aug 19, 2020

keewis deleted the silence-sphinx-warnings branch August 19, 2020 15:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Silence sphinx warnings #4286

Silence sphinx warnings #4286

keewis commented Jul 29, 2020 •

edited

keewis commented Jul 31, 2020

spencerkclark commented Jul 31, 2020

max-sixty commented Aug 6, 2020

dcherian commented Aug 12, 2020

keewis Aug 12, 2020

keewis commented Aug 12, 2020 •

edited

shoyer left a comment

shoyer Aug 13, 2020

keewis Aug 13, 2020

dcherian Aug 14, 2020

dcherian commented Aug 19, 2020

max-sixty commented Aug 19, 2020

Silence sphinx warnings #4286

Silence sphinx warnings #4286

Conversation

keewis commented Jul 29, 2020 • edited

keewis commented Jul 31, 2020

spencerkclark commented Jul 31, 2020

max-sixty commented Aug 6, 2020

dcherian commented Aug 12, 2020

keewis Aug 12, 2020

Choose a reason for hiding this comment

keewis commented Aug 12, 2020 • edited

shoyer left a comment

Choose a reason for hiding this comment

shoyer Aug 13, 2020

Choose a reason for hiding this comment

keewis Aug 13, 2020

Choose a reason for hiding this comment

dcherian Aug 14, 2020

Choose a reason for hiding this comment

dcherian commented Aug 19, 2020

max-sixty commented Aug 19, 2020

keewis commented Jul 29, 2020 •

edited

keewis commented Aug 12, 2020 •

edited