kylebarron
commented
1 month ago 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
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 https://github.com/developmentseed/cql2-rs/pull/30#discussion_r1791891512, we should discuss where we prefer to put Python docs for this sort of project.