Improve apidoc with pydoctor tool

[tisonkun]

Using the numpy doc style. This format is also compatible with pdoc by specifying --docformat=numpy.

To preview locally:

pip3 install pydoctor
pydoctor --make-html --html-viewsource-base=https://github.com/apache/pulsar-client-python/tree/main --docformat=numpy --theme=readthedocs --html-output=apidoc pulsar
cd apidoc
python3 -m http.server

Browse on localhost:8000.

cc @BewareMyPower @merlimat @shibd

[tisonkun]

Screen.Recording.2022-11-04.at.23.02.29.-.Compressed.with.FlexClip.mp4

[tisonkun]

The major motivation is that the style of pdoc is out of materialized and I suspect it provides worse reading experience.

An alternative is to replace pdoc with pdoc3:

pip3 install pdoc3
pdoc --html -o $(pwd)/apidoc --config "lunr_search={}" pulsar

But still, we should update several syntax errors. BTW, pdoc3 is a malicious fork of pdoc and IMO Apache basically discourages malicious fork and I'd try to avoid use it as possible.

[merlimat]

👍 👍

[BewareMyPower]

Could you add a instruction for how to generate the preview into README?

[tisonkun]

@BewareMyPower Thanks for your comments. Updated.