DOC: documenting cython class (eg Timestamp): "cyfunction is not a python function"

[jorisvandenbossche]

Follows from discussion in PR #5160.

When adding Timestamp in api.rst to document this class and its methods (as eg done in this commit jorisvandenbossche@3a8a41d), you get warnings when building the docs like for example:

WARNING: error while formatting arguments for pandas.Timestamp.to_period: 
<cyfunction Timestamp.to_period at 0x00000000057616C0> is not a Python 
function.

Timestamp is a python class in a cython file (so I suppose then it is a cython class). You get the warnings for all methods that are defined in this class (defined here https://github.com/pydata/pandas/blob/master/pandas/tslib.pyx#L130), but not for inherited functions of _Timestamp or datetime.

It seems that the generated docstring pages are built (so with the docstring rendered), but that Sphinx could not detect the signature.

Does somebody know how to let Sphinx handle cython classes/functions?

[jtratner]

does :cy:func: work? That'd be nice.

[jorisvandenbossche]

@jtratner What do you mean? If you include in api.rst

.. autosummary::
   :toctree: generated/

   Timestamp 

the docstrings of Timestamp and it methods are included in the docs, so I suppose just :func: should also work (eg :func:pandas.Timestamp.to_period``).

The issues are that it generates warnings when building the docs and the signatures are not included, but in itself it does work (as in: the docstrings are included in the generated docs).

[jtratner]

:func: is shorthand for :py:func: when you're in whatever python-ish mode sphinx defaults to - just wondering if it handled it that way. I thought you could also explicitly specify the type signature in autosummary for certain methods?