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/ > -- Nathaniel J. Smith -- https://vorpus.org _______________________________________________ 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/
