search

twisted / pydoctor

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

Define new field #456

Open SoyeonBaek opened 2 years ago

SoyeonBaek commented 2 years ago

I've written a epydoc to define new field in the following way. But Unknown Field errors occur if I run pydoctor on my project. I think it's because current version of pydoctor do not support newfield for reStructuredText. Is there any other mechanism for defining new field? Or do you have any plans to update?

:newfield contributor: Contributor, Contributors (Alphabetical Order)
:contributor: `Glyph Lefkowitz  <mailto:glyph@twistedmatrix.com>`__
:contributor: `Edward Loper  <mailto:edloper@gradient.cis.upenn.edu>`__
tristanlatr commented 2 years ago

Hi @SoyeonBaek

There is currently no way of defining custom fields.

Adding the newfield mechanism seems possible, though. Maybe we should not bother with plural handling (like epydoc) and provide simpler syntax, like: :newfield tag: label

Regarding implementation, we should add a new method: handled_newfield to the FieldHandler: https://github.com/twisted/pydoctor/blob/636787868caa2287ed791c97eefefafd6fa47eeb/pydoctor/epydoc2stan.py#L395

This method should dynamically patch self in order to add the required handle_<newfield> method. This method could simply add the new field content into a self.newfields: Dict[str, List[Field]] (that maps the name of the new fields to the docstring fields). Then we should use this new variable in the format function to include the new fields into the generated HTML.

We need to make a choice about the position of the new fields in the generated HTML, should they be before the regular fields or after ?

Cheers