[Async-sig] async documentation methods

[Alex Grönholm]

Yeah, but that doesn't answer my question :)


Chris Jerdonek kirjoitti 04.07.2017 klo 10:02:
> 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/