Re: [PATCH] doc: set up for autoapi / readthedocs compatibility

Subject:Re: [PATCH] doc: set up for autoapi / readthedocs compatibility

Date:Tue, 14 Jul 2020 23:42:40 +0200

To:David Bremner ,David Bremner ,


From:Floris Bruynooghe

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
> We'd presumable want to integrate the whole tree somehow into

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

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 --
To unsubscribe send an email to