Docs: incorporate pdoc to generate API docs

[cjrh]

Incorporating the suggestion in #174.

This is a little messy. Based on the pdoc example for Mkdocs, it seems you have to run a script to execute pdoc before the mkdocs pass. Then, because pdoc emits HTML, to get it into the mkdocs build you have to incorporate the HTML as "fake" markdown so that mkdocs will process the markdown files and incorporate it.

It works, but it's a little clunky. Here's the output on my dev machine:

There are issue with this. pdoc will use the installed tantivy module. This means that the readthedocs site will have to build the tantivy module which might turn out to be nontrivial. Instead, the pdoc execution could be done as part of CI, commiting the output markdown files (in the ./docs/api directory). That way, readthedocs only needs to operate on markdown files and no compilation is required.

[mocobeta]

Hi @cjrh,
thank you for investigating this in detail!

There are issue with this. pdoc will use the installed tantivy module. This means that the readthedocs site will have to build the tantivy module which might turn out to be nontrivial. Instead, the pdoc execution could be done as part of CI, commiting the output markdown files (in the ./docs/api directory). That way, readthedocs only needs to operate on markdown files and no compilation is required.

This makes sense to me too.
(We could run a CI job that generates the API docs files when merging PRs into the main branch.)