Improve docs: expose schemas

[simon-weber]

trafficstars

We need something like https://unofficial-google-music-api.readthedocs.org/en/develop/reference/metadata.html, but for every call. This can lessen reliance on static examples that aren't maintained (and cause confusion, eg #231).

One complication is that raw responses are typically transformed by client code before being returned from gmusicapi. I suppose we'd have to provide an optional function to transform the given schema. I can think of a few ways to implement this:

• a decorator that takes a schema and optional transform func, then modifies the wrapper function's docstring. I have no idea how this will interact with the docstring-copying code from the decorator module -- if that replaces an entry rather than add to it, things might get difficult. edit: actually, decorator's code should run after ours, so maybe we could just modify the wrapped function's docstring?
• a decorator like the previous, but that builds out schema information and adds it as an attribute on the function. At some later point (during __new__? __init__?) generic code builds these out and adds them to the docstring.

For presentation, I'm imagining an initially-folded section after the docs for each call. That'll keep the schemas close to the function definition, but avoid clutter (some of the schemas are big). Hopefully arbitrary html can be embedded with sphinx?

---

Somewhat off topic, but it seems like example responses should be handled similarly. There should also be a test that ensures a 1-to-1 mapping between schema fields and example fields.

[sauyon]

I agree. In fact, I think we should have the entire call logic - what to send, as well as what you receive. It would help people trying to port this to other languages. Also, I've been thinking about writing a server compatible with the this API, which would definitely need a separate API documentation. EDIT: Also would help me out while hacking on this library as well :).

I think that transformation by the API library is exactly what we should be doing. Having a standardized Song class and Playlist class that we can document completely separately from Google's initial returns means we can easily provide backward compatibility if, say, Google decides to radically change the API, which is not out of the question because they are in total control of both the server and the client.

In terms of the presentation, I'd think that having documentation for the Song/Playlist/whatever separately, as well as a completely separate protobuf API section would be nice.

[simon-weber]

Yeah, request schemas would be nice but I don't have static definitions of them in code.

We could get them without schema additions with a bit of trickery: you'd build the request kwargs for a call but substitute the param name for all dynamic params. You'd lose type information this way, though.

Having a standardized Song class and Playlist class...

a uniform model layer would be nice. I don't think it'd fit with the current level of abstraction, but it's something to talk about wrt https://github.com/simon-weber/Unofficial-Google-Music-API/issues/260.