search

twisted / pydoctor

This is pydoctor, an API documentation generator that works by static analysis.
https://pydoctor.readthedocs.io/
Other
179 stars 47 forks source link

Failure to process classifiers as part of consolidation fields in a reStructuredText docstring #765

Closed juur closed 3 months ago

juur commented 3 months ago

Using pydoctor 23.9.1 under Python 3.11.5, executing with args pydoctor --quiet --make-html --html-output docs --process-types --intersphinx-cache-path ./.sphinx-cache src/pyerp

The following snippet works fine:

"""A BusinessUnit is a top level organisational container.

:CVariables:
    `id`
        unique serial for this entity
"""

However, the following snippet generates an error:

"""A BusinessUnit is a top level organisational container.

:CVariables:
    `id` : int
        unique serial for this entity
"""

The error is:

bad docstring: Unexpected element in type specification field: element 'Text'. This value should only contain regular paragraphs with text or inline markup.

Based on the documentation, I believe this to be a bug as the classifiers should be processed in a definition list.

tristanlatr commented 3 months ago

Thanks for the bug report, it is linked to the —process-types options, it seem there is a bug Indeed.

tristanlatr commented 3 months ago

So here is the deal:

https://github.com/twisted/pydoctor/blob/9becf8528099c57ab06257b72b1858302fa779ab/pydoctor/epydoc/markup/_types.py#L79

We do not account for the cases where a Text node is directly put inside the document node. Which is what happened with consolidated fields. It should be a very quick fix.