Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make API docs easier to discover #407

Open
Nikratio opened this issue Jan 20, 2018 · 12 comments
Open

Make API docs easier to discover #407

Nikratio opened this issue Jan 20, 2018 · 12 comments

Comments

@Nikratio
Copy link

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
Copy link
Member

njsmith commented Jan 20, 2018

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
Copy link
Member

njsmith commented Jan 20, 2018

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

@Nikratio
Copy link
Author

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.

@Nikratio Nikratio changed the title Add reference documentation Make API docs easier to discover Jan 20, 2018
@njsmith
Copy link
Member

njsmith commented Jan 20, 2018

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
Copy link
Author

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
Copy link
Member

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
Copy link
Member

njsmith commented Jan 20, 2018

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
Copy link
Author

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
Copy link
Member

njsmith commented Jan 21, 2018

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
Copy link

xgid commented Jan 21, 2018

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
Copy link
Author

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
Copy link
Author

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants