Improve documentation

[jacobtomlinson]

@Cadair introduced me to automodapi today and it seems awesome. But it took some thorough explaining before I realised that and understood what it does.

I think a lot of the trouble I had could've been avoided with some improvements to the docs. After spending some time understanding what the package does I feel like I may have some insights into small things that could be done to improve things for others.

I don't really have the time to contribute these things myself, so this is a bit of a drive-by issue. Sorry!

What does the package actually do?

The sphinx-automodapi package provides Sphinx directives that help faciliate the automatic generation of API documentation pages for Python package modules.

The current description didn't give me a clear impression of what it was actually for. I think explaining that it is like automodule but 1000x better would be a good start.

Show what it does

This will add a section with the docstring of the module, followed by a list of functions, and by a list of classes. For each function and class, a full API page will be generated.

I read this section of text a few times and still wasn't sure what the output would be. Perhaps some sample code, with some sample RST and a screenshot of the resulting documentation would help here.

Show the inheritance graph

I skimmed over the section about the inheritance graph. I thought it sounded useful if you have a complex class hierarcy, but didn't fully grasp how nice and useful it looked.

Seeing this page really helped me understand how useful it was.

Improve the toctree

The menu bar has a lot of text and each section title didn't really help me understand what it was about.

Add examples

Both the automodapi and automodsumm pages have a thorough explanation of the options, but no examples. It would be really helpful to see example usage with code, rst and screenshots.