[Feature Request] Look into alternative API doc generators

[cretz]

Describe the solution you'd like

We should consider moving away from https://github.com/twisted/pydoctor for Python API docs. It was originally chosen because of how well it handled @overloads. But it doesn't really get updated much and is a bit buggy, e.g. https://python.temporal.io/temporalio.worker.WorkerDeploymentConfig.html is showing those as class variables (because it doesn't understand data classes) and is even missing default_versioning_behavior that is in source with a default.

Open to all options, but I think we want pure API docs generator, not like Sphinx where English docs come along with, but it's worth a try so long as python.temporal.io is pure API docs. Maybe also try https://pdoc.dev/. Or just check around the ecosystem.

[tristanlatr]

Hi @cretz,

Know that the next version of pydoctor should handle dataclasses and attrs-based classes with more grace. See PR twisted/pydoctor#656.

FWIW, The fact that pydcotor works solely based on static analysis (whereas sphinx autodoc and pdoc) is a great strength in terms of reliability (because doesn't rely on the runtime state of your python package); but any major feature (like dataclasses support) will be harder to implement because we need to infer everything from the abstract syntax trees only.

Anyhow... don't hesitate to open issues and contribute directly to pydoctor such that it meets your needs!

Cheers,