Clean up documentation

[rmb938]

The current documentation seems very random and the api docs are not well organized so finding specific information is difficult.

[rmb938]

Also are the docs more focused on github or ReadTheDocs? If ReadTheDocs using sphinx could help with organization.

See http://sphinx.readthedocs.org/en/latest/

[dnephin]

The api docs (http://docker-py.readthedocs.org/en/latest/api/) are ordered alphabetically, which seems logical to me. How would you suggest changing it?

[shin-]

In addition to what @dnephin said, there is a discussion about using Sphinx here: #454

[rmb938]

Well more of adding categories so I can click a link and only see all the api's related to images, or all the apis related to containers, ect..

The current layout just seems like a lot of information all on one page without anyway for drilling down and seeing specific apis.

So an example would be:

Someone is relatively new to docker and knows how to use commands but now wants to build things on top of the api. Looks at the docker-py RTD and sees a whole page of API docs but they are just interested in API's to do with containers. So now they have to scroll and look or CTRL+F for key words to find certain things.

There is also very few examples for things. So if someone new to python or just doesn't want to look through the api page wanting to do something i.e creating a new container, there isn't something that they can just look at and easily understand. Yes there are examples for port bindings and using volumes but those examples could be to complex for someone new to python or wanting to just get up and running very quickly.

[shin-]

Your last paragraph seems to point at some sort of quickstart guide, which could potentially be a good idea. It would probably assume the reader already knows python, though.

We could potentially separate the different API methods thematically, but that might cause confusion considering all of them still exist as methods of the same docker.Client class. Could be worked around by having a "Client index" that lists all the methods and links to the different pages, but the page hops might be irritating to some level.

[rmb938]

Yea a quickstart guide is what I was going for.

Also with sphinx at least the different API methods wouldn't need to be under different pages. I believe you just need to give it a different type of header and it will automatically group things in the left navbar. So under "Client API" there would be a container group or a images group and clicking that would scroll the page to that specific group.

[bfirsh]

Fixed in #1186! Also, continued "clean up documentation" discussion can continue in #836. :)