Documentation was rendered with epydoc and some custom extensions until cocos 0.5.5. Epydoc is long time unmaintained, and needs patchs to work with newer python and docutils versions, so a change to a well maintained doc library was needed.
Sphinx is the current de facto standard, so documentation will use sphinx.
Keep customization at a minimun to avoid the need of maintenace when sphinx changes.
This notes can help if a new ‘from scratch’ documentation build is desired.
Using sphinx 1.2 release , docutils 0.11, pygments 1.5
deleting items in doc/ that sphinx won’t use. (at that moment only doc/doc.css)
running:
cd doc sphinx-quickstartAnswered some interactive questions, renamed the old index.txt because sphinx-quickstart wants to generate a new one.
results committed at r1274, no attempt to build was performed
customize index.txt, conf.py, make.bat and Makefile (the later is untested) Notice ‘build’ will run apidoc + build each time Doing a build shows some warnings that will be addresed later; committed r1275
fixed some warnings with r1276-77, now only 6 unimportant warnings
At this point sphinx documentation is usable.
To build the documentation do a:
cd doc make.bat clean make.bat html (in unix-like systems replace make with Makefile)
I played a bit with the pyglet customizations for sphinx in the branch b_sphinx, but abandoned that because build times were much longer. (branch deleted at r1278)