[ann] sphinxcontrib-trio: make sphinx better at documenting functions/methods, esp. for async/await code
Hi all, I just released a new package, sphinxcontrib-trio: https://sphinxcontrib-trio.readthedocs.io/ It makes it easier to document many kinds of functions/methods in sphinx, including async functions, abstract methods, generators, etc. I originally wrote it for the trio [1] project, hence the name, but don't let that put you off -- there's nothing about it that's specific to trio, or even to async/await (except that projects that use async/await *really need* an extension like this). Really I think this extension ought to be a standard feature of sphinx. But in the mean time, it's pretty handy. -n [1] https://trio.readthedocs.io -- Nathaniel J. Smith -- https://vorpus.org
So are you going to try to upstream this? ;) On Fri, 12 May 2017 at 01:24 Nathaniel Smith <njs@pobox.com> wrote:
Hi all,
I just released a new package, sphinxcontrib-trio:
https://sphinxcontrib-trio.readthedocs.io/
It makes it easier to document many kinds of functions/methods in sphinx, including async functions, abstract methods, generators, etc.
I originally wrote it for the trio [1] project, hence the name, but don't let that put you off -- there's nothing about it that's specific to trio, or even to async/await (except that projects that use async/await *really need* an extension like this). Really I think this extension ought to be a standard feature of sphinx. But in the mean time, it's pretty handy.
-n
[1] https://trio.readthedocs.io
-- Nathaniel J. Smith -- https://vorpus.org _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
[dropped python-announce from CC list] On Fri, May 12, 2017 at 9:17 AM, Brett Cannon <brett@python.org> wrote:
So are you going to try to upstream this? ;)
Realistically, for me this is a side-project to a side-project, so it may require someone else do the integration work, but: https://github.com/sphinx-doc/sphinx/issues/3743 -n -- Nathaniel J. Smith -- https://vorpus.org
I like it! Do you have support for hybrid iterators/context managers: async with con.transaction() as tr # or tr = await con.transaction() and async for row in con.cursor(’SELECT …') # or cur = await con.cursor(‘SELECT …’) I.e. if I annotate `con.transaction` with both `:async:` and `:async-with:`, will it render two signatures? Yury On May 12, 2017 at 4:24:22 AM, Nathaniel Smith (njs@pobox.com) wrote:
Hi all,
I just released a new package, sphinxcontrib-trio:
https://sphinxcontrib-trio.readthedocs.io/
It makes it easier to document many kinds of functions/methods in sphinx, including async functions, abstract methods, generators, etc.
I originally wrote it for the trio [1] project, hence the name, but don't let that put you off -- there's nothing about it that's specific to trio, or even to async/await (except that projects that use async/await *really need* an extension like this). Really I think this extension ought to be a standard feature of sphinx. But in the mean time, it's pretty handy.
-n
[1] https://trio.readthedocs.io
-- Nathaniel J. Smith -- https://vorpus.org _______________________________________________ Async-sig mailing list Async-sig@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
[dropped python-announce from CC list] On Fri, May 12, 2017 at 9:23 AM, Yury Selivanov <yselivanov@gmail.com> wrote:
I like it!
Do you have support for hybrid iterators/context managers:
async with con.transaction() as tr # or tr = await con.transaction()
and
async for row in con.cursor(’SELECT …') # or cur = await con.cursor(‘SELECT …’)
I.e. if I annotate `con.transaction` with both `:async:` and `:async-with:`, will it render two signatures?
Right now if you combine those options then you'll get something like "async with await con.transaction() as tr" and "async for row in await con.cursor(sql_query)". Of course, the code generating this is trivial; just some if statements to construct strings, so it wouldn't be hard to make it do something different. But two questions: - The signatures sphinxcontrib-trio currently renders are also valid (though unusual), so how do you think it should decide which one is meant? 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 :-). - Do you have any examples in mind of sphinx rendering multiple signatures for the same function? I'm not sure what that looks like. Keep in mind that this is the actual signature at the top of the docs for the function, not like example code or something... so it would never say 'SELECT ...' anyway, it would have a list of the args+kwargs. -n -- Nathaniel J. Smith -- https://vorpus.org
On May 12, 2017 at 7:10:52 PM, Nathaniel Smith (njs@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
participants (3)
-
Brett Cannon -
Nathaniel Smith -
Yury Selivanov