[Async-sig] async documentation methods

[Chris Jerdonek]

On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronholm at nextday.fi> wrote:
> 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?

It looks like this is the issue (which Brett filed in Nov. 2015):
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 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/
>>>
>>
>>
>
> _______________________________________________
> 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/