search

twisted / pydoctor

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

Syntax error reports don't contain information about the error #806

Open RunDevelopment opened 1 month ago

RunDevelopment commented 1 month ago

Currently, syntax errors in doc strings are reported like this:

Generating objects inventory at docs/objects.inv
these 2 objects' docstrings contain syntax errors:
    spandrel.architectures.GRL.__arch.grl.GRL
    spandrel.architectures.GRL.__arch.grl.TransformerStage

This is not enough information. It says where an error happened, but not what the error is.

In my case, I have 100 lines in a single doc comment and no idea what the problem is. The page renders correctly, it's just objects.inv that's causing my CI to fail. I'm using the google docformat, but the same problem occurs with restructured text as well.

Please show the error message and ideally the line and column of the syntax error as well.

I would like the above report to look like something like this:

Generating objects inventory at docs/objects.inv
these 2 objects' docstrings contain syntax errors:
    spandrel.architectures.GRL.__arch.grl.GRL
        L16:4  Invalid character '*' or whatever, idk the actual error
    spandrel.architectures.GRL.__arch.grl.TransformerStage
        L94  Unexpected list in the middle of whatever

Running pydoctor -v does not give additional information about the above errors.

tristanlatr commented 1 month ago

Hello @RunDevelopment thanks for your feature request.

For the short term, please look for bad docstring errors in the pydoctor output. This should point you towards the right line numbers. Also note that numpy and google docstring formats currently introduces a slight offset in the docstring line numbers because the text is preprocessed to be transformed into regular restructuredtext (#807 ).

RunDevelopment commented 1 month ago

For the short term, please look for bad docstring errors in the pydoctor output.

Thank you! This has the error message 👍

I didn't find these until now, because I was searching for the documented class (e.g. spandrel.architectures.GRL.__arch.grl.GRL) as reported, but bad docstring errors log the file path. Maybe the qualified name of the docstring target should be logged as well?