### Navigation

- index
- modules |
- previous |
- cocos »
- Dev Notes »

# 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)

### Navigation

- index
- modules |
- previous |
- cocos »
- Dev Notes »