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)

Table Of Contents

Previous topic

Dev Notes

This Page