feat(bindings/python): add auto-generated api docs

[messense]

I hereby agree to the terms of the CLA available at: https://databend.rs/dev/policies/cla/

Summary

• Use pdoc to generate API docs.

[PsiACE]

It looks a bit complicated, I think pdoc might be much simpler.

[messense]

I don't mind switching to pdoc, though it can't document opendal.layers yet:

pdoc opendal/
pdoc server ready at http://localhost:8080
Warn: Error parsing type stubs for opendal:
Traceback (most recent call last):
  File "/Users/messense/.pyenv/versions/3.11.0/envs/test-3.11/lib/python3.11/site-packages/pdoc/doc_pyi.py", line 105, in include_typeinfo_from_stub_files
    imported_stub = _import_stub_file(module.modulename, stub_file)
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/messense/.pyenv/versions/3.11.0/envs/test-3.11/lib/python3.11/site-packages/pdoc/doc_pyi.py", line 40, in _import_stub_file
    eval(code, m.__dict__, m.__dict__)
  File "opendal/__init__.pyi", line 19, in <module>
    from .layers import ConcurrentLimitLayer, ImmutableIndexLayer, RetryLayer
ImportError: attempted relative import with no known parent package
 (/Users/messense/.pyenv/versions/3.11.0/envs/test-3.11/lib/python3.11/site-packages/pdoc/doc_pyi.py:107)

[messense]

And pdoc doesn't pickup docstrings in .pyi files with current setup.

[Xuanwo]

And pdoc doesn't pickup docstrings in .pyi files with current setup.

Related to mitmproxy/pdoc#239?

[messense]

And pdoc doesn't pickup docstrings in .pyi files with current setup.

Related to mitmproxy/pdoc#239?

Probably just need to move docstrings to Rust side.

[PsiACE]

Just an example #1614

[messense]

I don't mind switching to pdoc, though it can't document opendal.layers yet:

pdoc opendal/
pdoc server ready at http://localhost:8080
Warn: Error parsing type stubs for opendal:
Traceback (most recent call last):
  File "/Users/messense/.pyenv/versions/3.11.0/envs/test-3.11/lib/python3.11/site-packages/pdoc/doc_pyi.py", line 105, in include_typeinfo_from_stub_files
    imported_stub = _import_stub_file(module.modulename, stub_file)
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/messense/.pyenv/versions/3.11.0/envs/test-3.11/lib/python3.11/site-packages/pdoc/doc_pyi.py", line 40, in _import_stub_file
    eval(code, m.__dict__, m.__dict__)
  File "opendal/__init__.pyi", line 19, in <module>
    from .layers import ConcurrentLimitLayer, ImmutableIndexLayer, RetryLayer
ImportError: attempted relative import with no known parent package
 (/Users/messense/.pyenv/versions/3.11.0/envs/test-3.11/lib/python3.11/site-packages/pdoc/doc_pyi.py:107)

Can't solve this yet, this boils down to PyO3/pyo3#759 and the workaround doens't work with pdoc.

[Xuanwo]

I am not satisfied with the current state of the Layers API. Therefore, I am fine if we do not document any API related to layers at this time. Maybe we can setup the Operator related API first?

[suyanhanx]

We can update here together.

https://github.com/apache/incubator-opendal/blob/27abd5123c14fbc6eb3438197183640744ac47b3/website/docusaurus.config.js#L92-L96

[Xuanwo]

Hello, @messense. I apologize for the broken CI. It has been fixed now. Kindly update your branch and try again.

[Xuanwo]

Thanks a lot!

[suyanhanx]

Thanks.