sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.59k stars 2.12k forks source link

Autodoc fails to include members from ctypesgen bindings #10209

Closed mara004 closed 2 years ago

mara004 commented 2 years ago

Describe the bug

ctypesgen is a tool to automatically create Python bindings to C libraries via ctypes, which I am using for pypdfium2. It creates a long file (example: _pypdfium.py.txt) that contains lots of code snippets like this:

FPDF_TEXTRENDERMODE_FILL = 0# build_tar/include/fpdfview.h: 51
# build_tar/include/fpdfview.h: 546
try:
    FPDF_ERR_UNKNOWN = 1
except:
    pass
# build_tar/include/fpdf_transformpage.h: 122
for _lib in _libs.values():
    if not _lib.has("FPDFPage_GetCropBox", "cdecl"):
        continue
    FPDFPage_GetCropBox = _lib.get("FPDFPage_GetCropBox", "cdecl")
    FPDFPage_GetCropBox.argtypes = [FPDF_PAGE, POINTER(c_float), POINTER(c_float), POINTER(c_float), POINTER(c_float)]
    FPDFPage_GetCropBox.restype = FPDF_BOOL
    break

I noticed that sphinx-autodoc only recognises members of the first case, while all the others are missing.

This is how I am autodoc'ing the file in question:

.. automodule:: pypdfium2._pypdfium

With corresponding configuration in conf.py:

autodoc_preserve_defaults = True
autodoc_typehints_format = 'short'

autodoc_default_options = {
    'members': True,
    'undoc-members': True,
    'member-order': 'bysource',
}

How to Reproduce

$ git clone https://github.com/pypdfium2-team/pypdfium2.git
$ cd pypdfium2
$ git checkout pdfium_apidocs
$ make install
$ make docs-build docs-open

Expected behavior

sphinx-autodoc should include all members, also those that are wrapped with try/except or _lib.has(...).

Your project

https://github.com/pypdfium2-team/pypdfium2

Screenshots

No response

OS

Linux Ubuntu 20.04

Python version

3.8.10

Sphinx version

4.4.0

Sphinx extensions

sphinx.ext.autodoc

Extra tools

Chromium M98

Additional context

No response

mara004 commented 2 years ago

After analysing the situation more closely, I don't think it would make much sense to create documentation for a ctypesgen module. All that could be achieved would be the plain method and attribute names, which is not very useful.