issue_comments

I renamed from_store to load_store, let's discuss both in #3638. For the injected / accessor methods there is #3625.

:clap: Welcome to xarray!

on it

:+1: Wanna merge?

A grep over the code tells me that load_store is never used, tested or mentioned (from_store is mentioned but never defined or used): do we still support it?

I guess from_store mentions should be removed; let's open an issue for removing load_store. I don't know the backend code but it'd gone through multiple refactors so things may have been missed.

dump_to_store is mentioned and tested, so we definitely should put it somewhere (even if it is just api-hidden.rst).

Let's stick this in api-hidden.rst

I think you should merge this after making these changes. It's a large step forward. We can revisit once someone comes up with a solution for the injected methods.

I think once we decided what to do with the DataStore methods and how to treat the injected methods, we can merge?

Edit: I think we can just leave the accessor methods as is. This means we only have to decide what to do with dump_to_store and load_store. A grep over the code tells me that load_store is never used, tested or mentioned (from_store is mentioned but never defined or used): do we still support it? dump_to_store is mentioned and tested, so we definitely should put it somewhere (even if it is just api-hidden.rst).

this is fairly close now: bash grep -e "doc/[^/]*.rst" -e "<autosummary>" warnings gives us .../xarray/doc/generated/xarray.Dataset.rst:132:<autosummary>:1: WARNING: py:obj reference target not found: xarray.Dataset.dump_to_store .../xarray/doc/generated/xarray.Dataset.rst:132:<autosummary>:1: WARNING: py:obj reference target not found: xarray.Dataset.load_store .../xarray/doc/whats-new.rst:346: WARNING: py:meth reference target not found: Dataset.plot.scatter .../xarray/doc/whats-new.rst:431: WARNING: py:meth reference target not found: Dataset.plot.scatter .../xarray/doc/whats-new.rst:1068: WARNING: py:meth reference target not found: xarray.DataArray.plot.line .../xarray/doc/whats-new.rst:1789: WARNING: py:meth reference target not found: DataArray.plot.imshow which means only the injected methods and the DataStore related Dataset methods are left. If they are still supported, where should I put them?

no, not yet. There are a lot of warnings left even if I leave out the ones due to the parameter type.

Is this ready to merge?

The Data*Coordinates objects are returned by the coords attributes of DataArray and Dataset

Ah! I was wrong. These are public and have public methods that should be documented: see https://xarray.pydata.org/en/stable/data-structures.html#coordinates-methods

thanks for the review, @dcherian.

The Data*Coordinates objects are returned by the coords attributes of DataArray and Dataset. They are mostly treated as dict but they have a few public (i.e. not prefixed with an underscore) properties (e.g. dims), all of which don't have docstrings. I'll treat both classes as implementation detail.

Other than that, only the injection methods and the datastore methods remain for the manually written part. Unfortunately, the autodoc / autosummary warnings are due to a sphinx bug (see https://github.com/pydata/xarray/issues/3370#issuecomment-564124368), so our only option right now is to use nitpicky_ignore to silence them. I don't think we should, though. Instead, I'll try to silence all warnings that are not due to the bug and we can leave the rest to a potential round 4 or a sphinx / napoleon update.

I added a lot of new entries to api-hidden.rst, mostly the methods of CFTimeIndex that were inherited from pandas.Index. Is that okay? sphinx also complains about the attributes (properties?) so I would probably need to add more.

Edit: I also added Data*Coarsen to api-hidden.rst, but we may want to think about giving them the same status as Data*Rolling or Data*Resample: put them into their own section in api.rst.

running sphinx-build with -w warnings and executing grep -e "doc/[^/]*.rst" warnings returns .../xarray/doc/whats-new.rst:336: WARNING: py:meth reference target not found: Dataset.plot.scatter .../xarray/doc/whats-new.rst:421: WARNING: py:meth reference target not found: Dataset.plot.scatter .../xarray/doc/whats-new.rst:468: WARNING: py:class reference target not found: xarray.core.coordinates.DataArrayCoordinates .../xarray/doc/whats-new.rst:1059: WARNING: py:meth reference target not found: xarray.DataArray.plot.line .../xarray/doc/whats-new.rst:1091: WARNING: py:meth reference target not found: xarray.tutorial.open_dataset .../xarray/doc/whats-new.rst:1091: WARNING: py:meth reference target not found: xarray.tutorial.load_dataset .../xarray/doc/whats-new.rst:1778: WARNING: py:meth reference target not found: DataArray.__dask_scheduler__ .../xarray/doc/whats-new.rst:1780: WARNING: py:meth reference target not found: DataArray.plot.imshow .../xarray/doc/whats-new.rst:1957: WARNING: py:func reference target not found: xarray.show_versions .../xarray/doc/whats-new.rst:2029: WARNING: py:meth reference target not found: xarray.backends.PydapDataStore.open these are the broken links in the non-autodoc / autosummary documentation: * if I remember correctly, scatter, line and imshow not having a documentation is known and the link will probably be fixed once we get sphinx to document what I think @dcherian called "injection methods". * I'd say __dask_scheduler__ is not part of the public API so we can convert to double-backtick quoted * DataArrayCoordinates and DatasetCoordinates still exist, but they are never referenced by the docs. Are they part of the public API? * show_versions does not have a docstring (which could be really small) and is not referenced elsewhere in the docs. What should I do with it? * the tutorial functions do have docstrings. Should we mention them somewhere else? * all the datastore documentation pages have broken links to their methods. Should I also add them to api-hidden.rst?