Documentation

pyglet uses reStructuredText markup language for both the Programming Guide and the docstrings embedded in the code.

Build

The complete documentation can be generated using sphinx.

Requirements

  • sphinx: Documentation builder.
  • graphviz: If you want to generate graphs.

To build the documentation, execute:

./make.py docs

If the build succeeds, the web pages are in _build/html

Note

The documentation build configuration file is pyglet/doc/conf.py

Contents

pyglet/doc/index.txt: The first page of the documentation.

pyglet/doc/programming_guide: The first page of the programming guide.

pyglet/doc/internal:
Documentation for those working on Pyglet itself, such as how to make a release or how the ctypes library is used.

Docstrings

The API documentation is generated from the source code.

Example:
class Class1():
"""Short description.

Detailed explanation, formatted as reST.
Can be as detailed as it is needed.


:Parameters:
   Narrative description
   `arg1` : type description
       description

:return: return description
:since: pyglet 1.2

"""

property1 = None
"""This is an attribute.
"""


def _get_property2(self):
    """Getter Method

    :return: property1 value
    :rtype: property1 type
    """

def _set_property2(self, value):
    """Setter Method

    :param value: property1 value
    :type value: property1 type

    """

property2 = property(_get_property2, _set_property2,
                  doc='''Short description

This is another attribute.

:type: type
:see: something else
''')

Generation

In order to generate this documentation, several modifications have been done in sphinx.ext.autosummary, as well as some code in conf.py.

It does the following:

  • Find all modules and creates a tree.
  • Events are separated from regular methods.
  • Skip some modules, classes, functions and methods.

Structure

All the items are saved in the api folder, following the module hierarchy structure, and the page name is the full name of the item.

For example, the page containing the list of events of the Window class is:

api/pyglet/window/pyglet.window.Window.html#events

Templates

The files at pyglet/doc/_templates control all the process.

Module

  • Module documentation
  • Modules
  • Classes
  • Functions
  • Exceptions

Class

  • Inheritance diagram
  • Class documentation
  • Events
  • Methods
  • Attributes
  • Members documentation
  • Inherited members documentation (not indexed)

Function

  • Function documentation

Exception

  • Exception documentation

Omisions

Skipped members

The skip_member function in conf.py contains rules to prevent certain members to appear in the documentation

Due to the large number of members that were listed when generating, a modification in autosummary prevents all members that are not defined in the current module to appear in the member lists.

This means that if a module imports members like this:

from pyglet.gl import *

That members are not listed in the module documentation.

Warning

There is one exception to the rule, for clarity sake:

  • If a member is defined in module.base, and imported by module, it does appear in the module page lists.

Skipped modules

Some modules in pyglet can not be imported when documenting, so a black list in conf.py contains all the modules that are not to be documented:

  • pyglet.app.carbon
  • pyglet.app.cocoa
  • pyglet.app.win32
  • pyglet.app.xlib
  • pyglet.canvas.carbon
  • pyglet.canvas.cocoa
  • pyglet.canvas.win32
  • pyglet.canvas.xlib
  • pyglet.canvas.xlib_vidmoderestore
  • pyglet.font.carbon
  • pyglet.font.freetype
  • pyglet.font.freetype_lib
  • pyglet.font.quartz
  • pyglet.font.win32
  • pyglet.gl.agl
  • pyglet.gl.carbon
  • pyglet.gl.cocoa
  • pyglet.gl.glext_arb
  • pyglet.gl.glext_nv
  • pyglet.gl.glx
  • pyglet.gl.glx_info
  • pyglet.gl.glxext_arb
  • pyglet.gl.glxext_mesa
  • pyglet.gl.glxext_nv
  • pyglet.gl.lib_agl
  • pyglet.gl.lib_glx
  • pyglet.gl.lib_wgl
  • pyglet.gl.wgl
  • pyglet.gl.wgl_info
  • pyglet.gl.wglext_arb
  • pyglet.gl.wglext_nv
  • pyglet.gl.win32
  • pyglet.gl.xlib
  • pyglet.image.codecs.gdiplus
  • pyglet.image.codecs.gdkpixbuf2
  • pyglet.image.codecs.pil
  • pyglet.image.codecs.quartz
  • pyglet.image.codecs.quicktime
  • pyglet.input.carbon_hid
  • pyglet.input.carbon_tablet
  • pyglet.input.darwin_hid
  • pyglet.input.directinput
  • pyglet.input.evdev
  • pyglet.input.wintab
  • pyglet.input.x11_xinput
  • pyglet.input.x11_xinput_tablet
  • pyglet.libs.darwin
  • pyglet.libs.win32
  • pyglet.libs.x11
  • pyglet.media.drivers.directsound
  • pyglet.media.drivers.openal
  • pyglet.media.drivers.pulse
  • pyglet.window.carbon
  • pyglet.window.cocoa
  • pyglet.window.win32
  • pyglet.window.xlib

Note

To be able to document a module, it has to be importable when sys._is_epydoc is True.

Details

Build

Date 2013/03/31 01:03:29
pyglet version 1.2alpha1

Warnings

See the Sphinx warnings log file for details.

Table Of Contents