[doc] Improve API's documentation

[HerringtonDarkholme]

Napi doc now only lists methods and assume users have experience or mindsets about programmatic usage.

This is not universally true. To better guide users, the doc site should be rewritten into

• why
• guide
• examples
• caveats

Python should also have similar docs.

[gkapfham]

Hello @HerringtonDarkholme, I checked the public-facing documentation for a description of the Python API and I could not yet find it. If you can point me in the direction of this documentation and give me some suggestions for testing that you would like me to complete, I would be glad to try out the Python bindings and provide feedback. Thanks!

[HerringtonDarkholme]

Hi @gkapfham, sg-team has not yet enough time to prepare the Python API doc.

However, you can look at the test case https://github.com/ast-grep/ast-grep/tree/main/crates/pyo3/tests
to know the usage of Python API.

There is also a type declaration file for Python, which will be useful as well.
https://github.com/ast-grep/ast-grep/blob/main/crates/pyo3/ast_grep_py/ast_grep_py.pyi