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/
