sphinx-doc / sphinx-doc/sphinx

autodoc does not recognize Cython property as such

Open
#7,448 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc help wanted type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Because of implementation details, @property of Cython extension types are not the same as created by the builtin property function. For this reason, autodoc doesn't seem to be able to recognize these descriptor as such.

To Reproduce

First create a sample Cython module with the mentioned elements:

getter = property   # bypass Cython property hijack
setter = lambda fset: property(fset=fset, doc=fset.__doc__)     # noqa


cdef class Spam:
    @property
    def foo(self) -> int: return 42

    @getter
    def bar(self) -> float: return 6.9

    @setter
    def baz(self, value: bool) -> None: pass

as well as a setup.py for compilation

from distutils.core import setup
from Cython.Build import cythonize

setup(name='autospam',
      ext_modules=cythonize('cyspam.pyx',
                            compiler_directives={'binding': True}))

Use pip install . to install and cyspam should be importable.

Now if we create a sample project with the following content (I was a bit lazy to think of the documentations for the properties):

.. autoclass:: cyspam.Spam
   :undoc-members:

the rendered HTML looks like this:

2020-04-09T18:21:24

Expected behavior

It is expected that foo shows up as a property as well.

Sample project

autospam.zip

Environment info
  • OS: [e.g. Unix/Linux/Mac/Win/other with version]
  • Python version: 3.7.7
  • Sphinx version: 3.0.0
  • Sphinx extensions: sphinx.ext.autodoc
  • Extra tools: Cython

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the sphinx.ext.autodoc entry point and reproduce the behavior with cyspam.pyx, setup.py, and the sample autoclass directive. Check the rendered output for Spam; done means the Cython foo descriptor is recognized and presented as a property alongside the other descriptors.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.