[Async-sig] async documentation methods

[Andrew Svetlov]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/async-sig/attachments/20170630/cf97ae74/attachment.html>