Make API docs easier to discover

[Nikratio]

At the moment, there does not seem to be any reference documentation for trio. I am looking for a complete description of the API, with all methods,functions, classes, and parameters. For example, right now I read about the start_soon() method of the nursery object and was wondering what other methods there might be (start_right_awayt?).

[njsmith]

I believe that all public methods, functions, classes, and parameters are documented in the manual. Can you elaborate on what problem you're having? Were you unable to find a link to the manual? Where did you look?

[njsmith]

For example, the nursery interface is documented here: https://trio.readthedocs.io/en/latest/reference-core.html#task-related-api-details

[Nikratio]

Ah, yes. That's exactly what I was looking for, thanks! So for me this is actually a discoverability problem. It looks to me as if the API documentation is sort of sprinkled through a more tutorial-like text (the whole "Trio'score functionaly" section reads like a tutorial to me). It would be great to have a top-level entry in the navigation bar that says "API reference" and consists of all the API descriptions concatenated right after each other.

[njsmith]

Ah, gotcha. I do plan to reorganize the docs when I have a chance, and I'll try to keep that in mind. Part of the problem there though is that for things like the nursery and cancellation semantics, you really do need a chunk of prose to explain the semantics :-). If you want a full understanding of Trio's semantics (which I don't know if you do, but presumably that's the point of a reference manual), then you really need to read everything on that page through the "Tasks let you do multiple things at once" section. After that things settle down more into the classic "here's a class, here's its methods" style, with occasional headers giving context for why you want a class.

[Nikratio]

Yeah, but once you've read everything once, it becomes pretty tedious if you don't remember if it was nursery.startSoon, nursery.start_soon, nursery.run_soon or nursery.schedule_task() :-). That's where an API reference comes in handy.

[bluetech]

I agree. Being already familiar with the API, often I just want a quick reference/overview sort of thing. IMO it shouldn't include the full documentation, just link to the appropriate section. Something like the top section of any doxygen page (random example). This is also useful for discoverability.

[njsmith]

Probably the closest thing that Sphinx provides out of the box is the index: https://trio.readthedocs.io/en/latest/genindex.html

I'm trying to think of what the perfect solution would look like here, that doesn't involve writing two versions of the manual :-). Do you know of any other sphinx-using projects that have solved this particularly well and we could refer to?

[Nikratio]

Doesn't autodoc give you that pretty much for free? I think all you need is a section that lists the top-level objects, e.g.

API Reference
=============

.. currentmodule:: trio

Classes
-------

.. autoclass:: Nursery
   :members:

.. autoclass:: socket
   :members:

.. autoexception:: TooSlowError
   :members:

I haven't checked, but maybe you can even put :members: right under the module name and get away with 4 lines :-).

[njsmith]

Hmm, yeah, interesting idea. But that will end up repeating a ton of text, somewhat out of context, which I worry will make it confusing to searchers (e.g. if google sends you here and gives you out-of-context information, instead into the main docs -- also duplicate content like this tends to make google treat you like a spammer).

I think a more useful version of this would be like a super-detailed table-of-contents, that lists all the top-level classes/functions/constants, and maybe even class methods, as a big list of links into the main manual. So you'd be able to glance at this list to remind yourself of what different features exist and answer simple questions like "was it nursery.startSoon or nursery.start_soon?", or click through to get the full information in context. This seems like it should be doable with a Sphinx extension. (And the great thing about an extension is that it'd always be up to date!)

Also I guess another thing that would be useful along these lines is a "reference card" or "cheat sheet" – one card, lots of small text, something you can print out and put on your desk next to the keyboard, sort of like this one or this one (lots more here). Making a good one of these really does require some attention and thought though – not something we can teach a computer to do automatically :-). I won't have time to work on making a reference card soon myself, but if someone else wants to it'd be awesome.

[xgid]

Another really helpful way of accessing API documentation is the Dash API browser (with clones for Linux and Windows available like Velocity or Zeal).

The good news are that there's a Python application, doc2dash, which seems to make all the hard work of generating the documentation set from the Sphinx generated documents. I haven't tried it, but looks promising.

Just my two cents!

[Nikratio]

I was never able to make much use of printed cheatsheets, so my vote would go for the Autodoc solution, even if that means repetition :-). I'm not sure what you mean with "out of context". I just randomly looked at the docstrings for open_nursery, Cancelled and open_context_scope and they seem to stand very well on their own. The documentation in the manual at https://trio.readthedocs.io/en/latest/reference-core.html#trio.The%20cancel%20scope%20interface doesn't seem to refer to much context either.

Actually, it would already be a big improvement if the docstrings for eg the cancel scope or nursery object were available in Python and could be read with e.g. help(trio.Nursery) - but the actual classes seem to be hidden away somewhere.

[Nikratio]

Another example: I was just wondering if there is a trio function that tells me it I'm running in an async context or not. I couldn't find it, but I am not at all sure that it really doesn't exist. Having a comprehensive list of all API functions would have helped immensely to either find the function, or to be more confident that it really doesn't exist.

Couldn't you just tell the Google spider to ignore these pages of you're worried about bad entry points?