[Async-sig] [ann] sphinxcontrib-trio: make sphinx better at documenting functions/methods, esp. for async/await code

[Yury Selivanov]

On May 12, 2017 at 7:10:52 PM, Nathaniel Smith (njs at pobox.com) wrote:
> > - The signatures sphinxcontrib-trio currently renders are
> also valid
> (though unusual), so how do you think it should decide which one
> is
> meant?

Ideally, IMO, it should render it like this:

async with Connection.transaction()
await Connection.transaction()
    docstring

> I can see why your API looks like that, but it is a bit
> clever... as you know my personal style guide is that functions
> should
> either support being called like 'await foo()' or 'foo()' but
> never
> both :-).

Yeah, I’m still not sure if it was a good idea :)  asyncpg uses
this trick for a few APIs.

> - Do you have any examples in mind of sphinx rendering multiple
> signatures for the same function? I'm not sure what that looks
> like.

I *think* I saw Sphinx rendering two function signatures
one on top of another, but I can’t remember where.

Anyways, the extension looks quite useful, I’ll try it out!


Yury