On Mon, Jul 3, 2017 at 11:49 PM, Alex Grönholm <alex.gronh...@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 <br...@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.svet...@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 <dim...@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@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@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@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@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@python.org https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/
