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.
autosummary
extension: Adds the hidden property and the capability to skip some modules and membersNote
The patching requires a standard sphinx
version 1.1.3
All the *.rst
files in the _template
folder configure the layout of the API documentation.
The entry point is _template/package.rst
.
The custom sphinx theme is in the ext/theme
folder.
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.
Some things can not be imported when documenting, or are not to be documented,
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:
module.base
, and imported by module
, it does appear in the module
page lists.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
.