Add API reference to documentation site about tantivy-py HOT 11 OPEN

I tried a few things, and it seems that mkdocstrings doesn't do a good job of pulling out the docstrings from the rust source. So I guess that means pdoc is better.

from tantivy-py.

I didn't know mkdocstrings, but it seems to parse the Python code with Griffle parser (https://mkdocstrings.github.io/griffe/docstrings/) and try to directly extract the docstring from the source instead of pulling it from __doc__. So unfortunatelly this wouldn't be a help for our purposes.

from tantivy-py.

The current workflow is I log into readthedocs on my own personal account and click "sync". I'm not happy with this, but I don't currently have enough permissions on this github repo to get the webhook working. Once the webhook is setup, docs deployment will be automatic.

from tantivy-py.

@cjrh do you know which permission you need?

from tantivy-py.

@fmassot I think either I need "write" access, or I can add you or another admin to the readthedocs site and you can generate the integration there. Long term that is probably best anyway, so that I am not the only one with access to the readthedocs site.

• Documentation on readthedocs about the integration for github->readthedocs: https://docs.readthedocs.io/en/stable/guides/setup/git-repo-automatic.html
• Project page for tantivy-py on readthedocs: https://readthedocs.org/projects/tantivy-py/

This is the page where the integration can be performed:

When I click "resync" it fails:

If you create a login on readthedocs (make sure to use your github OAuth login), I can add your account to the tantivy-py project on readthedocs, and then you will be able to successfully click that Resync webhook button, which should work because it'll use the permissions on your github OAuth token. Then I won't need any permissions change on tantivy-py.

Just let me know your login name on readthedocs and I'll add it to the project.

from tantivy-py.

@mocobeta This example at mkdocs shows integration of pdoc into a mkdocs build: https://github.com/mitmproxy/pdoc/tree/main/examples/mkdocs/

There is a comment that says:

mkdocstrings is a great alternative to pdoc if you are in the mkdocs ecosystem anyways.

Do you have personal experience that supports sticking with pdoc over mkdocstrings?

from tantivy-py.