Silence sphinx warnings (#4286)

* generate documentation for the a few missing CFTimeIndex attributes

* properly use continuation lines

* add a missing quote

* delete the note about the removed auto_combine

* replace auto_combine with combine_by_coords

* set the current module in dask.rst

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

* add the new CFTimeIndex methods to api-hidden

* don't link to CFTimeIndex.__repr__

* don't try to link to the datetime accessor

* fix a few more docstrings

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

* add type aliases

* map ComplexWarning to numpy.ComplexWarning

* fix more docstrings

* add some missing methods and properties to api-hidden

* more aliases

* fix a few more docstrings

* properly reference ... (Ellipsis)

* update the docstrings of dataset

* update the docstrings of DataArray

* remove the references to CFTimeOffset

* fix a lot more docstrings

* fix even more docstrings

* remove a few more workarounds for a sphinx bug

* use sphinx version 3.2

* remove a few misspellings of bool and optional

* fix more docstrings

* more fixes

* remove the mixed markup since it is not supported by the preprocessor

* use double instead of single quotes in docstrings

* make sure the standard default notation is used everywhere

* add a missing end quote

* don't use nested parameter definition lists

* update some outdated links to the pandas docs

* update some more docstrings

* mark a parameter as optional

* more docstrings

* use code blocks instead of literal blocks with doctest lines

* add back a removed colon

* convert the glossary page to a sphinx glossary

* add term descriptions for names and scalars

* preprocess types but don't use :param:

because that will separate combined parameter docs by duplicating the description

* link to the terms

* don't try to link to the repr method

* update the definition of scalar according to the review

* Update doc/terminology.rst

Co-authored-by: Maximilian Roos <[email protected]>

* Update doc/terminology.rst

Co-authored-by: Maximilian Roos <[email protected]>

* fix a bad merge

* fix the docstring of cftime_range

Co-authored-by: Maximilian Roos <[email protected]>
Co-authored-by: Deepak Cherian <[email protected]>

Author: 3 people

ci/requirements/doc.yml

@@ -24,7 +24,7 @@ dependencies:
   - rasterio>=1.1
   - seaborn
   - setuptools
-  - sphinx=3.1
+  - sphinx=3.2
   - sphinx_rtd_theme>=0.4
   - sphinx-autosummary-accessors
   - zarr>=2.4

doc/api-hidden.rst

@@ -52,6 +52,7 @@
    core.rolling.DatasetCoarsen.var
    core.rolling.DatasetCoarsen.boundary
    core.rolling.DatasetCoarsen.coord_func
+   core.rolling.DatasetCoarsen.keep_attrs
    core.rolling.DatasetCoarsen.obj
    core.rolling.DatasetCoarsen.side
    core.rolling.DatasetCoarsen.trim_excess
@@ -104,6 +105,8 @@
    core.resample.DatasetResample.dims
    core.resample.DatasetResample.groups
 
+   core.rolling.DatasetRolling.argmax
+   core.rolling.DatasetRolling.argmin
    core.rolling.DatasetRolling.count
    core.rolling.DatasetRolling.max
    core.rolling.DatasetRolling.mean
@@ -115,11 +118,15 @@
    core.rolling.DatasetRolling.var
    core.rolling.DatasetRolling.center
    core.rolling.DatasetRolling.dim
+   core.rolling.DatasetRolling.keep_attrs
    core.rolling.DatasetRolling.min_periods
    core.rolling.DatasetRolling.obj
    core.rolling.DatasetRolling.rollings
    core.rolling.DatasetRolling.window
 
+   core.weighted.DatasetWeighted.obj
+   core.weighted.DatasetWeighted.weights
+
    core.rolling_exp.RollingExp.mean
 
    Dataset.argsort
@@ -188,6 +195,7 @@
    core.rolling.DataArrayCoarsen.var
    core.rolling.DataArrayCoarsen.boundary
    core.rolling.DataArrayCoarsen.coord_func
+   core.rolling.DataArrayCoarsen.keep_attrs
    core.rolling.DataArrayCoarsen.obj
    core.rolling.DataArrayCoarsen.side
    core.rolling.DataArrayCoarsen.trim_excess
@@ -238,6 +246,8 @@
    core.resample.DataArrayResample.dims
    core.resample.DataArrayResample.groups
 
+   core.rolling.DataArrayRolling.argmax
+   core.rolling.DataArrayRolling.argmin
    core.rolling.DataArrayRolling.count
    core.rolling.DataArrayRolling.max
    core.rolling.DataArrayRolling.mean
@@ -249,11 +259,15 @@
    core.rolling.DataArrayRolling.var
    core.rolling.DataArrayRolling.center
    core.rolling.DataArrayRolling.dim
+   core.rolling.DataArrayRolling.keep_attrs
    core.rolling.DataArrayRolling.min_periods
    core.rolling.DataArrayRolling.obj
    core.rolling.DataArrayRolling.window
    core.rolling.DataArrayRolling.window_labels
 
+   core.weighted.DataArrayWeighted.obj
+   core.weighted.DataArrayWeighted.weights
+
    DataArray.argsort
    DataArray.clip
    DataArray.conj
@@ -277,6 +291,13 @@
    core.accessor_dt.DatetimeAccessor.days_in_month
    core.accessor_dt.DatetimeAccessor.daysinmonth
    core.accessor_dt.DatetimeAccessor.hour
+   core.accessor_dt.DatetimeAccessor.is_leap_year
+   core.accessor_dt.DatetimeAccessor.is_month_end
+   core.accessor_dt.DatetimeAccessor.is_month_start
+   core.accessor_dt.DatetimeAccessor.is_quarter_end
+   core.accessor_dt.DatetimeAccessor.is_quarter_start
+   core.accessor_dt.DatetimeAccessor.is_year_end
+   core.accessor_dt.DatetimeAccessor.is_year_start
    core.accessor_dt.DatetimeAccessor.microsecond
    core.accessor_dt.DatetimeAccessor.minute
    core.accessor_dt.DatetimeAccessor.month
@@ -291,6 +312,14 @@
    core.accessor_dt.DatetimeAccessor.weekofyear
    core.accessor_dt.DatetimeAccessor.year
 
+   core.accessor_dt.TimedeltaAccessor.ceil
+   core.accessor_dt.TimedeltaAccessor.floor
+   core.accessor_dt.TimedeltaAccessor.round
+   core.accessor_dt.TimedeltaAccessor.days
+   core.accessor_dt.TimedeltaAccessor.microseconds
+   core.accessor_dt.TimedeltaAccessor.nanoseconds
+   core.accessor_dt.TimedeltaAccessor.seconds
+
    core.accessor_str.StringAccessor.capitalize
    core.accessor_str.StringAccessor.center
    core.accessor_str.StringAccessor.contains
@@ -365,6 +394,7 @@
    Variable.min
    Variable.no_conflicts
    Variable.notnull
+   Variable.pad
    Variable.prod
    Variable.quantile
    Variable.rank
@@ -407,6 +437,8 @@
 
    IndexVariable.all
    IndexVariable.any
+   IndexVariable.argmax
+   IndexVariable.argmin
    IndexVariable.argsort
    IndexVariable.astype
    IndexVariable.broadcast_equals
@@ -436,6 +468,7 @@
    IndexVariable.min
    IndexVariable.no_conflicts
    IndexVariable.notnull
+   IndexVariable.pad
    IndexVariable.prod
    IndexVariable.quantile
    IndexVariable.rank
@@ -538,6 +571,16 @@
    ufuncs.tanh
    ufuncs.trunc
 
+   plot.plot
+   plot.line
+   plot.step
+   plot.hist
+   plot.contour
+   plot.contourf
+   plot.imshow
+   plot.pcolormesh
+   plot.scatter
+
    plot.FacetGrid.map_dataarray
    plot.FacetGrid.set_titles
    plot.FacetGrid.set_ticks
@@ -547,11 +590,16 @@
    CFTimeIndex.any
    CFTimeIndex.append
    CFTimeIndex.argsort
+   CFTimeIndex.argmax
+   CFTimeIndex.argmin
    CFTimeIndex.asof
    CFTimeIndex.asof_locs
    CFTimeIndex.astype
+   CFTimeIndex.calendar
+   CFTimeIndex.ceil
    CFTimeIndex.contains
    CFTimeIndex.copy
+   CFTimeIndex.days_in_month
    CFTimeIndex.delete
    CFTimeIndex.difference
    CFTimeIndex.drop
@@ -562,6 +610,7 @@
    CFTimeIndex.equals
    CFTimeIndex.factorize
    CFTimeIndex.fillna
+   CFTimeIndex.floor
    CFTimeIndex.format
    CFTimeIndex.get_indexer
    CFTimeIndex.get_indexer_for
@@ -602,6 +651,7 @@
    CFTimeIndex.reindex
    CFTimeIndex.rename
    CFTimeIndex.repeat
+   CFTimeIndex.round
    CFTimeIndex.searchsorted
    CFTimeIndex.set_names
    CFTimeIndex.set_value
@@ -688,15 +738,20 @@
    backends.NetCDF4DataStore.is_remote
    backends.NetCDF4DataStore.lock
 
+   backends.H5NetCDFStore.autoclose
    backends.H5NetCDFStore.close
    backends.H5NetCDFStore.encode
    backends.H5NetCDFStore.encode_attribute
    backends.H5NetCDFStore.encode_variable
+   backends.H5NetCDFStore.format
    backends.H5NetCDFStore.get_attrs
    backends.H5NetCDFStore.get_dimensions
    backends.H5NetCDFStore.get_encoding
    backends.H5NetCDFStore.get_variables
+   backends.H5NetCDFStore.is_remote
    backends.H5NetCDFStore.load
+   backends.H5NetCDFStore.lock
+   backends.H5NetCDFStore.open
    backends.H5NetCDFStore.open_store_variable
    backends.H5NetCDFStore.prepare_variable
    backends.H5NetCDFStore.set_attribute

doc/combining.rst

@@ -244,16 +244,6 @@ in this manner.
 Combining along multiple dimensions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note::
-
-  There are currently three combining functions with similar names:
-  :py:func:`~xarray.auto_combine`, :py:func:`~xarray.combine_by_coords`, and
-  :py:func:`~xarray.combine_nested`. This is because
-  ``auto_combine`` is in the process of being deprecated in favour of the other
-  two functions, which are more general. If your code currently relies on
-  ``auto_combine``, then you will be able to get similar functionality by using
-  ``combine_nested``.
-
 For combining many objects along multiple dimensions xarray provides
 :py:func:`~xarray.combine_nested` and :py:func:`~xarray.combine_by_coords`. These
 functions use a combination of ``concat`` and ``merge`` across different

doc/conf.py

@@ -100,8 +100,58 @@
 autosummary_generate = True
 autodoc_typehints = "none"
 
-napoleon_use_param = True
+napoleon_use_param = False
 napoleon_use_rtype = True
+napoleon_preprocess_types = True
+napoleon_type_aliases = {
+    # general terms
+    "sequence": ":term:`sequence`",
+    "iterable": ":term:`iterable`",
+    "callable": ":py:func:`callable`",
+    "dict_like": ":term:`dict-like <mapping>`",
+    "dict-like": ":term:`dict-like <mapping>`",
+    "mapping": ":term:`mapping`",
+    "file-like": ":term:`file-like <file-like object>`",
+    # special terms
+    # "same type as caller": "*same type as caller*",  # does not work, yet
+    # "same type as values": "*same type as values*",  # does not work, yet
+    # stdlib type aliases
+    "MutableMapping": "~collections.abc.MutableMapping",
+    "sys.stdout": ":obj:`sys.stdout`",
+    "timedelta": "~datetime.timedelta",
+    "string": ":class:`string <str>`",
+    # numpy terms
+    "array_like": ":term:`array_like`",
+    "array-like": ":term:`array-like <array_like>`",
+    "scalar": ":term:`scalar`",
+    "array": ":term:`array`",
+    "hashable": ":term:`hashable <name>`",
+    # matplotlib terms
+    "color-like": ":py:func:`color-like <matplotlib.colors.is_color_like>`",
+    "matplotlib colormap name": ":doc:matplotlib colormap name <Colormap reference>",
+    "matplotlib axes object": ":py:class:`matplotlib axes object <matplotlib.axes.Axes>`",
+    "colormap": ":py:class:`colormap <matplotlib.colors.Colormap>`",
+    # objects without namespace
+    "DataArray": "~xarray.DataArray",
+    "Dataset": "~xarray.Dataset",
+    "Variable": "~xarray.Variable",
+    "ndarray": "~numpy.ndarray",
+    "MaskedArray": "~numpy.ma.MaskedArray",
+    "dtype": "~numpy.dtype",
+    "ComplexWarning": "~numpy.ComplexWarning",
+    "Index": "~pandas.Index",
+    "MultiIndex": "~pandas.MultiIndex",
+    "CategoricalIndex": "~pandas.CategoricalIndex",
+    "TimedeltaIndex": "~pandas.TimedeltaIndex",
+    "DatetimeIndex": "~pandas.DatetimeIndex",
+    "Series": "~pandas.Series",
+    "DataFrame": "~pandas.DataFrame",
+    "Categorical": "~pandas.Categorical",
+    "Path": "~~pathlib.Path",
+    # objects with abbreviated namespace (from pandas)
+    "pd.Index": "~pandas.Index",
+    "pd.NaT": "~pandas.NaT",
+}
 
 numpydoc_class_members_toctree = True
 numpydoc_show_class_members = False
@@ -278,9 +328,9 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    ("index", "xarray.tex", "xarray Documentation", "xarray Developers", "manual")
-]
+# latex_documents = [
+#     ("index", "xarray.tex", "xarray Documentation", "xarray Developers", "manual")
+# ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
@@ -307,7 +357,7 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [("index", "xarray", "xarray Documentation", ["xarray Developers"], 1)]
+# man_pages = [("index", "xarray", "xarray Documentation", ["xarray Developers"], 1)]
 
 # If true, show URL addresses after external links.
 # man_show_urls = False
@@ -318,17 +368,17 @@
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        "index",
-        "xarray",
-        "xarray Documentation",
-        "xarray Developers",
-        "xarray",
-        "N-D labeled arrays and datasets in Python.",
-        "Miscellaneous",
-    )
-]
+# texinfo_documents = [
+#     (
+#         "index",
+#         "xarray",
+#         "xarray Documentation",
+#         "xarray Developers",
+#         "xarray",
+#         "N-D labeled arrays and datasets in Python.",
+#         "Miscellaneous",
+#     )
+# ]
 
 # Documents to append as an appendix to all manuals.
 # texinfo_appendices = []

doc/dask.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: xarray
+
 .. _dask:
 
 Parallel computing with Dask
@@ -90,7 +92,7 @@ use :py:func:`~xarray.open_mfdataset`::
     xr.open_mfdataset('my/files/*.nc', parallel=True)
 
 This function will automatically concatenate and merge datasets into one in
-the simple cases that it understands (see :py:func:`~xarray.auto_combine`
+the simple cases that it understands (see :py:func:`~xarray.combine_by_coords`
 for the full disclaimer). By default, :py:meth:`~xarray.open_mfdataset` will chunk each
 netCDF file into a single Dask array; again, supply the ``chunks`` argument to
 control the size of the resulting Dask arrays. In more complex cases, you can