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 patches 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 in docstrings

Please use 4 spaces indentation.

Tabs usually break things, convert them to spaces.

Inline literal text: ``my_literal_text`` -> my_literal_text. (in link syntax ~ is a modifier that suppress 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()

Note

If the class, method, attribute or function exists in the cocos project, prepending the name with a dot is normally sufficient. This works as well for argument types

• link to a class :class:`.CocosNode` -> CocosNode

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

Link to another generated html (example to link drom the api to a top level document):

• `euclid docs <../euclid.html>`_

Functions and Methods docstring

We use Napoleon extension from Sphinx. Docstrings are laid out using the Google style. The docstring should contain a section for Arguments (if they are present in the signature) and for the Return type if different from None.

Examples:

def add(self, child, z=0, name=None):
    """Add the child and then update the manager's focus / viewport.

    Args:
        child (CocosNode): The node to add. Normally it's a
            :class:`ScrollableLayer`.
        z (int) : z-order for this child.
        name (str) : The name of this child. [Optional]
    """

def pixel_to_screen(self, x, y):
    """Look up the screen-space pixel matching the Layer-space pixel.

    Account for viewport, layer and screen transformations.

    Arguments:
        x (int): x coordinate in map space
        y (int): y coordinate in map space

    Returns:
        tuple[int, int]: coordinates in screen space
    """

Here are some guidelines when writing documentation

• The content should be precise enough so that anyone can understand what the class, method or function does.

• No markup in docstring’s first line. That line is presented raw by editors in autocomplete tooltips, so the markup looks weird.

• Don’t linkify class A or function f mentions in their own docstring(s). The reader is already in the class / function doc, so the link adds nothing except visual noise. It is fine to link to some specific subppart, like :method:…

• Use triple double quotes to delimit docstrings.

• When a subclass changes a bit some baseclass methods, and the baseclass method’s docstring is large, it is better to signal only the differences with the baseclass method and to point to the base for extra explanations.