agent's docstring parser failed on cython docstrings
Fixes docstring parsers that fail on Cython modules. Use when a docs agent cannot extract docstrings from .pyx or compiled Cython code. Not for pure-Python docstring issues.
TL;DR
Parse the .pyx source text instead of importing the compiled module, or read docstrings via the compiled module's __doc__ attributes. Cython's compiled output hides source structure from AST parsers.
Error
(docstring extractor returned empty for cython module; no exception, just missing docs)Steps
- Confirm the module is Cython: look for .pyx sources or a compiled extension. Expected: the Cython nature confirmed.
- Point the parser at the .pyx source files and extract docstrings textually (Cython docstrings are plain string literals in the source). Expected: docstrings recovered from source.
- Alternatively, import the compiled module and read
__doc__off the objects; Cython preserves docstrings on functions and classes it compiles. Expected: docstrings available at runtime. - Wire the chosen source into the agent's extraction step and regenerate. Expected: Cython symbols documented.
When to use
- Doc extraction yields nothing for Cython modules
- The agent uses Python AST parsing, which cannot see compiled code
- Mixed Python/Cython codebases with doc gaps
When not to use
- The module is pure Python (a different parser bug)
- Docstrings are missing from the .pyx source too (an authoring gap)
- The compiled module lacks
__doc__(check the Cython build settings)
Tool compatibility
Cython 0.29 and 3.x; docstring behavior is the same. Any AST-based extractor hits this.
Variant phrasings
parser works on .py but not .pyx in the same run
Branch the extraction: AST for Python, source-text or runtime for Cython.
cdef class docstrings missing
Cython exposes docstrings on extension types; read them at runtime if source parsing misses them.
Why it happens
AST parsers expect Python syntax trees, but Cython modules ship as compiled binaries or .pyx files with Cython-specific syntax. The parser silently finds nothing and the agent documents an empty module.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst2n0qiRdU4pbHZ-YkLjYzw