[Async-sig] async documentation methods

[Brett Cannon]

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 at 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 at 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 at 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 at python.org
> https://mail.python.org/mailman/listinfo/async-sig
> Code of Conduct: https://www.python.org/psf/codeofconduct/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/async-sig/attachments/20170630/69642be0/attachment.html>