Documentation

This is the pyglet documentation, generated with Sphinx.

Details:

Date 2023/01/05 18:32:23
pyglet version 1.4.11

Note

See the Sphinx warnings log file for errors.

Writing documentation

Familiarize yourself with Sphinx and reStructuredText.

Literature

The home page is pyglet/doc/index.rst. This file create three toctrees:

  • The programming guide
  • The API docs
  • The development guide, which you are reading now

Source code

The API documentation is generated from the source code docstrings via autodoc and a few custom extensions.

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

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

:Ivariables:
   `arg1`
       description

.. versionadded:: 1.2

'''

attribute1 = None
'''This is an attribute.

More details.
'''

#: This is another attribute.
attribute2 = None

def __init__(self):
    '''Constructor

    :parameters:
       `arg1` : type
          description
    '''

    self.instance_attribute = None
    '''This is an instance attribute.
    '''

def method(self):
    '''Short description.

    :returns: return description
    :rtype: returned type
    '''

def _get_property1(self):
    '''Getter Method contains docstrings for a property

    :return: property1 value
    :rtype: property1 type
    '''

def _set_property1(self, value):
    '''Setter Method docstrings are ignored
    '''

property1 = property(_get_property1, _set_property1,
                  doc='''Override docstring here if you want''')

Pyglet has a special role for deprecations, :deprecated:.

Source Output
:deprecated: Do not use

Warning

Deprecated. Do not use

Building

The complete documentation can be generated using sphinx. Make sure you prepare your environment as stated in Development environment.

To build the documentation, execute:

./make.py docs --open

Note

Due to a bug in Sphinx, documentation generation currently only works using Python 3.x.

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

Optionally the standalone way to build docs is through setup.py or make.

# using setup.py (output dir: _build in project root)
python setup.py build_sphinx

# make (make.bat for windows)
cd doc
make html

HTML Theme

Note

The custom theme was disabled in 2019 and replaced with the standard Read the Docs theme sphinx_rtd_theme.

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