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.

Hints for some common markup operations

please use 4 spaces indentation

tabs usually break things, convert them to spaces

inline literal text: ``:class:`` -> :class:

(in link syntax ~ is a modidier that supress the high parts in a dotted name)

link to a cocos module: :mod:`~cocos.cocosnode` -> cocosnode

link to a cocos module: :mod:`cocos.cocosnode` -> cocos.cocosnode

link to a class: :class:`~cocos.cocosnode.CocosNode` -> CocosNode

link to a method: :meth:`~cocos.cocosnode.CocosNode.add` -> add()

link to a method:

:meth:`CocosNode.add<cocos.cocosnode.CocosNode.add>` -> CocosNode.add()

link to a function: :func:`cocos.tiles.load` -> cocos.tiles.load()

There are other roles like

:data: -> Reference a module-level variable.

:const: -> Reference a defined constant. This may be a Python variable that is not intended to be changed.

:attr: -> Reference a data attribute of an object.

:exc: -> Reference an exception. A dotted name may be used.

:obj: -> Reference an object of unspecified type. Useful e.g. as the default_role.

Link to a section or some arbitrary point in any document:

  • declare a label at the target location with .. _labelname: (the ‘_’ is not part of labelname)
  • write the link as :ref:`TextToShowInLink<labelname>` (brackets included)
  • if TextToShowInLink is ommited the ref should be just before a section and the section title will be used as the text to show in the link
  • labelname must be unique across all documents
Link to another document in the current sphinx build:
  • :doc:`TextToShowInLink<documentName>` (brackets included)
  • :doc:`documentName` (will show the document title in the link)