Documentation
This is the pyglet documentation, generated with Sphinx.
Details:
Date |
2023/06/08 08:11:35 |
pyglet version |
2.0.7 |
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.