DOC: Show constructor arguments for some classes in `pd.series.offsets`
State: open

This contributes to https://github.com/pandas-dev/pandas/issues/52431 

In that issue, the goal is to show the arguments for the constructors for the various offsets, which are all in `pyx` files.  

The problem is that `sphinx` doesn't pick up the arguments for `__init__()` in those files.  It seems that if you have `class` that is a not a `cdef class`, you have to have a `__new__()` method so the docs show up. This PR does this for `YearEnd`, by creating a `cdef _YearEnd` class. and then `YearEnd` is a regular class with `__new__()` calling `__new__()` of `_YearEnd`. So, if you preview the docs from this MR, you will see that `YearEnd` now shows its constructor.


If this PR is accepted, then we can get the community to do the work of separating the classes into "public" and "private" ones and adding adding the `__new__()` methods to the other documented offset classes and they can also add a `Parameters` section to those classes.  Note that for `YearEnd`, I had to change the docs from `Attributes` to `Parameters` to make it so that the docstrings are validated.



Labels:
name: Docs

Comments:
/preview

No strong opinions about this, but if the examples need the okexcept on windows sounds like this change is breaking things on windows, no? I guess I'm missing something, if you can clarify. But it would be better to fix the underlying problem, I don't think we should add okexcept unless we document exceptions.
> No strong opinions about this, but if the examples need the okexcept on windows sounds like this change is breaking things on windows, no? I guess I'm missing something, if you can clarify. But it would be better to fix the underlying problem, I don't think we should add okexcept unless we document exceptions.

No, the change is needed to just build the regular documentation (without this change) on Windows.  It has something to do with how sphinx calls cython and that doesn't seem to work right on Windows.  Not sure exactly what the problem is.

> No strong opinions about this, but if the examples need the okexcept on windows sounds like this change is breaking things on windows, no? I guess I'm missing something, if you can clarify. But it would be better to fix the underlying problem, I don't think we should add okexcept unless we document exceptions.

I found a better fix in #61686 .  So the `okexcept` is not there any more.
/preview

/preview
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/61605/
> If this PR is accepted, then we can get the community to do the work of separating the classes into "public" and "private" ones and adding adding the `__new__()` methods to the other documented offset classes and they can also add a `Parameters` section to those classes.

This seems like a very heavy handed code change for docs.
> From the linked issue:
> 
> > It turns out that making the constructor arguments appear from PYX files that are imported 3 levels in the hierarchy doesn't work right with Sphinx.
> 
> Has this been reported?

It was a problem in our repo.  It is fixed in this PR in `doc/source/index.rst.template`

> > If this PR is accepted, then we can get the community to do the work of separating the classes into "public" and "private" ones and adding adding the `__new__()` methods to the other documented offset classes and they can also add a `Parameters` section to those classes.
> 
> This seems like a very heavy handed code change for docs.

No disagreement there.  But I don't see another way of getting these constructors documented unless we work out something with the sphinx developers.

Note that there is a similar problem for `Interval` (https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Interval.html#pandas.Interval) .  For `Timestamp`, `Timedelta`, and `Period`, the same pattern is used so that the constructors show up in the docs, i.e., there is a private `cdef` class and the public class is a subclass of the private one, and the public one has all the docs.


I believe this is https://github.com/cython/cython/issues/3873.

@jbrockmendel - any thoughts here?
This came up in the last dev call.  I think Irv's solution was to make a non-cdef class with the docstring.  The perf impact was about 100ns on construction which we agreed was not a big deal (just kind of janky).

> For Timestamp, Timedelta, and Period, the same pattern is used so that the constructors show up in the docs

FWIW im pretty sure that pattern is used because we implement a `__new__` method, which I don't think you can do in a cdef class.
Is this something that can be reverted once sphinx/cython fixes something upstream? if so, can there be a `# TODO(sphinx3.14.159): ...` attached to these
> Is this something that can be reverted once sphinx/cython fixes something upstream? if so, can there be a `# TODO(sphinx3.14.159): ...` attached to these

Maybe.  I don't know how easy the reversion would be.   But if we make this change, we can also better document all the offset methods/properties and avoid the exceptions that appear in https://github.com/pandas-dev/pandas/blob/faf3bbb1d7831f7db8fc72b36f3e83e7179bb3f9/ci/code_checks.sh#L81