===================
Documentation Notes
===================

Making the switch to sphinx
===========================

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.

Guidelines for sphinx customization
===================================

Keep customization at a minimun to avoid the need of maintenace when sphinx changes.

Steps for initial sphinx support
================================

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-quickstart
    
    Answered 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)

