More professional feel for API reference

[djnugent]

Original posted here dronekit/dronekit-python#310 (comment)

The API reference page for dronekit python is hard to follow and looks very foreign to a programmer. I have stopped going there because it is easier to look at the source code then find what I am looking for on that page.

I suggest we try to match the format of current python API documentation. This will make the experience more familiar and easy to comprehend.

Here are a few python examples:
http://docs.opencv.org/modules/highgui/doc/reading_and_writing_images_and_video.html
https://docs.python.org/2/library/logging.html

Notable characteristics:
-Header/page break for every function(i.e. distinguishable dividers)
-Bold function names
-shows how the function is called in one line
-Lists and describes parameters
-Plenty of white space!
-Class name is listed in front of function name(when applicable)

Non essentials:
-Basic color scheme. Not too crazy
-Show deprecated methods

Other examples:
-Java docs has a very clean, extensible layout. I have never seen it used with python but is a great resource for an API

[hamishwillee]

Also maybe expand out the API reference as a TOC in the sidebar.

@kaitlynhova - I agree this could be better. Do you think you could find time to improve this further?

[kaitlynhova]

Yes! Now that the dronekit docs have been around for a few months l think it'd be great to improve on the overall look and refine how we display our info. -- What do you think of this new look (via Johan) for desktop and mobile? -->

[djnugent]

That looks nice!
I think it could use bars behind header(but that is just me)

I was commenting specifically on the API Reference page which wasn't shown in those sketches.
http://python.dronekit.io/automodule.html

[kaitlynhova]

ah, gotcha -- If we update the styles on the API reference page it will update how all of the docs look, which is probably a good thing at this point.

[hamishwillee]

@kaitlynhova @djnugent Yes, this is MUCH prettier.

If we update the styles on the API reference page it will update how all of the docs look, which is probably a good thing at this point.

Yes, it is likely to be a little better, but it probably won't address most of the points Daniel made (or add the class/function structure into the sidebar). Can we have some examples of how you think it will look in the API Reference?

[hamishwillee]

@kaitlynhova You've gone quiet on this :-) Any progress/ETA?

[kaitlynhova]

@hamishwillee : sorry for the delay! My time has been spoken for in order to get Blackbox out the door. I'll ask and see if I can get this going on Dronekit and get back to y'all.

[hamishwillee]

Thanks @kaitlynhova - that'll teach you to have other priorities :-)

[kaitlynhova]

Hey y'all --- I don't have time to knock this out right now because of other priorities (Blackbox), but I'd really like to keep this issue open for the future. These are all good ideas, but I wish that I had more time right now.

[hamishwillee]

@kaitlynhova Understood. Hope you have time to look at this again sometime soon. I'll keep nagging on a regular basis.