Python documentation

[gadomski]

We should flesh out the Python documentation. We could use readthedocs, but I'd personally recommend mkdocs-material deployed as Github Pages to https://developmentseed.github.io/cql2-rs, with top-level docs about the entire workspace and then Python docs underneath.

Per #30 (comment), we should discuss where we prefer to put Python docs for this sort of project.

[kylebarron]

I'm glad we're on the same page about mkdocs-material 😄 (sphinx 🤮)

with top-level docs about the entire workspace and then Python docs underneath.

You can see how I do it in geoarrow-rs. A top-level mkdocs website, plus another separate mkdocs deployment for the Python API. This has its own mkdocs.yml and is deployed with --deploy-prefix python/ https://github.com/geoarrow/geoarrow-rs/blob/87992ccb5e2b78a3b9975f2e29afbc9fa3a63ccf/.github/workflows/python-docs.yml#L83

where we prefer to put Python docs for this sort of project.

It's not just a choice of where is most convenient to put docs, it's that that choice changes which tools are able to see docs.

If you document your #[pyfunction] functions with /// style docstrings, those will get assigned to the Python __doc__ attribute, but will not be available to static code analysis. So for example it will work with the ? operator in IPython/Jupyter to see the docstring, but it won't show in VSCode.

Alternatively, if you put the docstrings in the pyi file, then those docstrings will be available to all static code analyzers, but not put on the __doc__ attribute, and so won't be available at runtime.

As far as I know, the only way to have both is to have a full Python shim around the Rust code

[gadomski]

As far as I know, the only way to have both is to have a full Python shim around the Rust code

Yuk. It's a small package so we probably can do the lift to do both, but 🤞🏼 that gets sorted at some point.