Doc folder refactorization

[GoogleCodeExporter]

I've made ​​some improvements, especially cleaning and organization.

Now sphinx is giving several warnings, some due to the way files are organized 
was not very clear. And especially because we need to call autosummary before 
you can reference API things in toctree directives.

The modified doc folder is at https://code.google.com/r/txema-pyglet-doc

Sphinx conf.py
--------------

Cleaned, only the essential code is left, and two configuration sections: 
pyglet and sphinx.

All sphinx modifications (Events documenter) and helper functions (write 
built.rst and blacklist.rst) moved to ext/sphinx_mod.py

Autosummary patch
-----------------
Autosummary generates all the /doc/api filesystem. 

Now doc/pyglet.txt contains the directive with the some modules commented out, 
but conf.py is intended to control what modules are to be documented, so this 
is unnecessary. Testing framework also needs an autosummary, thats why now 
sphinx can't find the docs and throws a warning. This autosummary diretives are 
now at index.txt, and you can then use toctree directives anywhere.

Implemented a new :hidden: option, so it generates the api folder first, 
without any output in the docs.

The patched autosummary extension is in ext/autosummary

API Templates
-------------

Recovered package.rst, so the first page can be different of the submodule 
pages.

ReST structure
--------------

All is now in one file: index.txt is the entry point for all.

HTML custom theme
-----------------

Sphinx now uses a custom theme, located at doc/ext/theme folder.

Files organization
------------------

doc/main.txt -> useless, generates "duplicate object" warnings, deleted
doc/tree.txt -> document isn't included in any toctree, deleted
doc/internals.txt -> merged into index.txt
doc/logo5.svg -> not used, but moved to doc/_static/logo5.svg
doc/doc.css -> not needed, now there is a custom theme at doc/ext/theme.

Original issue reported on code.google.com by tx...@nabla.net on 7 Dec 2013 at 2:39

[GoogleCodeExporter]

Original comment by useboxnet on 7 Dec 2013 at 4:33

• Changed state: Accepted
• Added labels: Component-Docs

[GoogleCodeExporter]

This issue was closed by revision 917682ca9126.

Original comment by useboxnet on 7 Dec 2013 at 7:30

• Changed state: Fixed

[GoogleCodeExporter]

Thanks a lot Txema!

Your changes improve pyglet's doc generation a lot; still some minor things, 
but this is looking good.

Added your name to the contributors: 
https://code.google.com/p/pyglet/source/detail?r=32b8c99e39bba69cc6e79696a3ef9d3
c8c7951c3

Original comment by useboxnet on 7 Dec 2013 at 7:34