Yeah, but that doesn't answer my question :)
Chris Jerdonek kirjoitti 04.07.2017 klo 10:02:
On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronholm@nextday.fi> wrote:
The real question is: why doesn't vanilla Sphinx have any kind of supportIt looks like this is the issue (which Brett filed in Nov. 2015):
for async functions which have been part of the language for quite a while?
https://github.com/sphinx-doc/sphinx/issues/2105
--Chris
Nathaniel Smith kirjoitti 01.07.2017 klo 13:35:
If we're citing curio and sphinxcontrib-asyncio I guess I'll also______________________________
mention sphinxcontrib-trio [1], which was inspired by both of them
(and isn't in any way specific to trio). I don't know if the python
docs can use third-party sphinx extensions, though, and it is a bit
opinionated (in particular it calls async functions async functions
instead of coroutines).
For the original text, I'd probably write something like::
You acquire a lock by calling ``await lock.acquire()``, and release
it with ``lock.release()``.
-n
[1] https://sphinxcontrib-trio.readthedocs.io/en/latest/
On Fri, Jun 30, 2017 at 8:31 AM, Brett Cannon <brett@python.org> wrote:
Curio uses `.. asyncfunction:: acquire` and it renders as `await
acquire()`
at least in the function definition.
On Fri, 30 Jun 2017 at 03:36 Andrew Svetlov <andrew.svetlov@gmail.com>
wrote:
I like "two methods, `async acquire()` and `release()`"
Regarding to extra markups -- I created sphinxcontrib-asyncio [1]
library
for it. Hmm, README is pretty empty but we do use the library for
documenting aio-libs and aiohttp [2] itself
We use ".. comethod:: connect(request)" for method and "cofunction" for
top level functions.
Additional markup for methods that could be used as async context
managers:
.. comethod:: delete(url, **kwargs)
:async-with:
:coroutine:
and `:async-for:` for async iterators.
1. https://github.com/aio-libs/sphinxcontrib-asyncio
2. https://github.com/aio-libs/aiohttp
On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dimaqq@gmail.com> wrote:
Hi all,--
I'm working to improve async docs, and I wonder if/how async methods
ought to be marked in the documentation, for example
library/async-sync.rst:
""" ... It [lock] has two basic methods, `acquire()` and `release()`.
...
"""
In fact, these methods are not symmetric, the earlier is asynchronous
and the latter synchronous:
Definitions are `async def acquire()` and `def release()`.
Likewise user is expected to call `await .acquire()` and `.release()`.
This is user-facing documentation, IMO it should be clearer.
Although there are examples for this specific case, I'm concerned with
general documentation best practice.
Should this example read, e.g.:
* two methods, `async acquire()` and `release()`
or perhaps
* two methods, used `await x.acquire()` and `x.release()`
or something else?
If there's a good example already Python docs or in some 3rd party
docs, please tell.
Likewise, should there be marks on iterators? async generators? things
that ought to be used as context managers?
Cheers,
d.
_______________________________________________
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/
Thanks,
Andrew Svetlov
_______________________________________________
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/
_______________________________________________
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/
_________________
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/
_______________________________________________
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/