On Sun 12 Jul 2020 at 09:02 -0300, David Bremner wrote:

> sphinx-autoapi seems nicer conceptually (it parses the docs rather
> than importing them),

TIL about sphinx-autoapi, agree it's nicer conceptually.

> but it also generates a ton of warnings, so
> leave the default as autodoc.
> ---
>
> You can see the results of this (for now) at https://notmuch.readthedocs.io/en/rtdtest/
> We'd presumable want to integrate the whole tree somehow into notmuchmail.org

Saldy it seems to struggle with a fair bit of things.  E.g. it does
manage to create a Database.MODE attribute, but it doesn't figure out
that this is the Mode enum and thus doesn't document the fact you have
two options: MODE.READ_ONLY and MODE.READ_WRITE.  There are obviously a
bunch of other enums where this matters.

It could be that these things are solvable by using more autodoc-style
directives:
https://sphinx-autoapi.readthedocs.io/en/latest/reference/directives.html

But I wonder if the autodoc one will always be better because of the
dynamic nature.  E.g. mapping notmuch2._database.Mode to
notmuch2.Database.MODE on the actual Public API.

I didn't actually try out how much better autodoc does, I should
probably try that too before commenting further.
_______________________________________________
notmuch mailing list -- notmuch@notmuchmail.org
To unsubscribe send an email to notmuch-leave@notmuchmail.org