Generate and publish API reference pages
- Dominant language
- C++
- Stars
- 3.9k
- Forks
- 1k
- Avg merge
- 4d 16h
- Merged PRs (30d)
- 47
Description
We have enough user-facing APIs to add a dedicated `Reference` section on our user website.
## Python bindings
Most of our Python classes and functions have docstrings, but the files are scattered throughout our codebase and split across several module namespaces and pip packages.
We could use `mkdocstrings` with our new mkdocs site:
* https://mkdocstrings.github.io/
* https://chrieke.medium.com/documenting-a-python-package-with-code-reference-via-mkdocs-material-b4a45197f95b
https://wiki.python.org/moin/DocumentationTools has more options. [Doxygen](https://www.doxygen.nl/index.html) could be nice, as it supports all the languages we use.
## TFLite bindings
TFLite / TFLite Java bindings can probably just link to TFLite's docs for API references, with differences highlighted on our pages.
## C API
The API headers are well documented (example: [`iree/base/api.h`](https://github.com/google/iree/blob/main/iree/base/api.h)) but the documentation is split across many files (example: [`iree/vm/api.h`](https://github.com/google/iree/blob/main/iree/vm/api.h) just exports various headers from `iree/vm/`). Aggregating into reference pages like https://mlir.llvm.org/docs/LangRef/ or https://mlir.llvm.org/doxygen/namespacemlir.html could be helpful.
## Java bindings
Our Java bindings are experimental and incomplete at the moment. If we develop them into a larger, supported API, we could use Javadoc or Doxygen.
## MLIR Dialects
We generate documentation for our MLIR dialects and publish them today at https://google.github.io/iree/Dialects. These are not user-facing (for most, but not all, definitions of "IREE user"), but it's useful to discuss them here too. Tablegen doc generation uses https://github.com/google/iree/blob/main/build_tools/cmake/iree_tablegen_doc.cmake to generate markdown files
Contributor guide
Assessment
This issue has not been assessed yet.