Add Series.str,Series.dt, and Series.cat accessors to docs

[scharlottej13]

• Closes Series.str / Series.dt methods missing from Docs #8599
• Tests added / passed
• Passes pre-commit run --all-files

I added the Series.str methods and Series.dt accessors to dataframe-api.rst, but am having trouble generating the autosummary. The specific Sphinx warning is WARNING: autosummary: failed to import Series.str.zfill, e.g., for all newly added lines.

I first tried to mimic the pandas docs, copying the changes made in https://github.com/pandas-dev/pandas/pull/9322. Then I tried using sphinx-autosummary-accessors, which is reflected in this PR. Would very much appreciate ideas/suggestions at this point, I'm not quite sure what else to try!

[keewis]

sphinx-autosummary-accessors requires the attribute to be accessible from the class, so e.g. Series.str.zfill shouldn't raise an AttributeError.

The reason this currently fails is because Series.str uses cache_readonly, which works like the builtin property: if accessed on the class object (__get__ is called with obj=None), it will return itself instead of the object it wraps. See also pydata/xarray#3988 for more discussion.

In summary, you might need to use a custom descriptor like pandas does (this is what we chose in xarray), or get pandas to change their implementation of cache_readonly / vendor it here.

[scharlottej13]

Thanks @keewis for taking the time to explain this. After looking through the links you shared, it seems like even with using a custom descriptor (e.g. the pandas example you linked) we still would run into problems, since in Dask the Accessor class reads the methods from the _meta object.

After chatting w/ @ian-r-rose @ncclementi, creating a new auto-documenter class might be an option, where I could get the docstrings from creating a Series instance. Is this something you tried already with xarray?

cc @jsignell

[keewis]

since in Dask the Accessor class reads the methods from the _meta object.

I see what you mean, this does indeed not work with the existing documenters in sphinx-autosummary-accessors.

Is this something you tried already with xarray?

While I did consider to instantiate the class in the accessor documenter I never actually tried it because changing the descriptor seemed easier (and I could follow what pandas did).

In any case, feel free to ping me if you need help, and I would also be happy to include those instantiating Accessor* documenters and their templates in sphinx-autosummary-accessors.

[jcrist]

I've pushed a patch up that refactors our accessor implementation to define all methods/properties statically (and did a bunch of other cleanliness fixes while I was at it). Things are almost working now, but I'm a bit confused what's still broken. Current status:

• Code tests pass locally (so implementation works as intended)
• Docs are accessible on instances (e.g. some_series.str.capitalize.__doc__ exists and is correct)
• Docs are accessible on class methods (e.g. dd.Series.str.capitalize.__doc__ exists and is correct)
• Docs are accessible on class properties (e.g. dd.Series.dt.date.__doc__ exists and is correct)
• make html runs (with some warnings) and generates docs pages for all accessor methods/properties

However, the accessor methods aren't documenting correctly. The accessor property docs are all working perfectly, but the methods show up with no docstring and as data.

I'm not sure what the issue is - @keewis do you have any thoughts?

[scharlottej13]

@jcrist this looks great!!!

However, the accessor methods aren't documenting correctly. The accessor property docs are all working perfectly, but the methods show up with no docstring and as data.

I changed the template from autosummary/accessor_attribute.rst to autosummary/accessor_method.rst and I think this fixed the issue:

[keewis]

you might have to split this in two parts: one for properties like Series.dt.day (using the accessor_attribute template), and another for the methods (using the accessor_method template).

[jcrist]

Ah, nice catch. That's a bit unfortunate that this is needed. Knowing nothing about how sphinx works - is this a sphinx limitation, or is it something that this extension could handle with the same template for both?

[keewis]

it's more like that is what pandas did the last time I checked. It would probably be possible to detect whether the attribute is a descriptor or a method and automatically use the appropriate documenter, but I never really tried.

Edit: I'm not entirely sure, but this seems to work for pandas.Series.cat

Also, at least for the projects I work on the split serves as a reminder that those are called differently (I'm not too familiar with dask.dataframe, though)

[jcrist]

This should be good to go, will merge once tests pass.

[keewis]

the missing docstring for Series.dt.freq will have to be fixed in pandas, which also doesn't seem to have a docstring (although it has a description, which is a bit weird)