Pyglet documentation system

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

It is a sphinx standard configuration file, but adds some requirements of pyglet package.

All the modifications to sphinx patching are in the ext folder.

  • Separate Events from regular methods.
  • autosummary extension: Adds the hidden property and the capability to skip some modules and members

Note

The patching requires a standard sphinx version 1.1.3

API Templates

All the *.rst files in the _template folder configure the layout of the API documentation.

The entry point is _template/package.rst.

HTML Theme

The custom sphinx theme is in the ext/theme folder.

ReST files

The literature is a set of *.txt files.

The entry point is index.txt.

The autosummary directive at index.txt directive is mandatory, it generates all the API documentation files.

Omisions

Some things can not be imported when documenting, or are not to be documented,

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.com
  • pyglet.compat
  • pyglet.font.carbon
  • pyglet.font.freetype
  • pyglet.font.freetype_lib
  • pyglet.font.quartz
  • pyglet.font.win32
  • pyglet.font.win32query
  • 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.lib
  • pyglet.libs
  • pyglet.media.avbin
  • 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.

Known bugs

  • The Window class attributes are not documented because they are defined at BaseWindow class.

Table Of Contents

Previous topic

Documentation

Next topic

tests.test