[Async-sig] async documentation methods

[Nathaniel Smith]

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 at 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 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/
>
>
> _______________________________________________
> 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/
>



-- 
Nathaniel J. Smith -- https://vorpus.org