[Async-sig] async documentation methods

[Alex Grönholm]

The real question is: why doesn't vanilla Sphinx have any kind of 
support for async functions which have been part of the language for 
quite a while?


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