pyglet uses reStructuredText markup language for both the Programming Guide and the docstrings embedded in the code.
The complete documentation can be generated using sphinx.
Requirements
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
pyglet/doc/index.txt: The first page of the documentation.
pyglet/doc/programming_guide: The first page of the programming guide.
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
''')
|
---|
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:
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
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
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:
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:
Note
To be able to document a module, it has to be importable when sys._is_epydoc is True.
Build
Date | 2013/03/31 01:03:29 |
pyglet version | 1.2alpha1 |
Warnings
See the Sphinx warnings log file for details.