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?

[sonots]

I am not sure whether this is in your case, but it seems insepect.isfunction(cyfuction) returns True from python 3.4 https://groups.google.com/forum/#!topic/cython-users/FvcMPk9n2X8. Using python >= 3.4 would resolve the issue.

[jorisvandenbossche]

That issue might be related, but it is not yet fully solved in any case, as we are using Python 3.6 for the doc build on travis (eg https://travis-ci.org/pandas-dev/pandas/jobs/291468074), and there are still some warnings like

/tmp/doc/source/api.rst:1773: WARNING: error while formatting arguments for pandas.Timestamp.today: <cyfunction Timestamp.today at 0x7fdffe22b6c0> is not a Python function

[jorisvandenbossche]

This blog http://opendreamkit.org/2017/06/09/CythonSphinx/ might be relevant (maybe not for a solution, but at least it gives some explanation of why it fails)

[jorisvandenbossche]

#18202 fixed this by including the signature on the first line of the docstring. I think this is a sufficient solution for now (@TomAugspurger ?)

[jorisvandenbossche]

Closed by #18202