1Documentation
2=============
3
4This is the pyglet documentation, generated with `Sphinx`_.
5
6.. _Sphinx: https://sphinx-doc.org
7
8.. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
9
10.. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
11
12Details:
13
14.. include:: build.rst
15
16.. note::
17
18   See the `Sphinx warnings log file <../warnings.txt>`_ for errors.
19
20
21Writing documentation
22---------------------
23
24Familiarize yourself with `Sphinx`_ and `reStructuredText`_.
25
26Literature
27^^^^^^^^^^
28
29The home page is ``pyglet/doc/index.rst``. This file create three toctrees:
30
31* The programming guide
32* The API docs
33* The development guide, which you are reading now
34
35Source code
36-----------
37
38The API documentation is generated from the source code docstrings via
39`autodoc`_ and a few custom extensions.
40
41:Example:
42
43   .. code-block:: python
44
45      class Class1():
46      '''Short description.
47
48      Detailed explanation, formatted as reST.
49      Can be as detailed as it is needed.
50
51      :Ivariables:
52         `arg1`
53             description
54
55      .. versionadded:: 1.2
56
57      '''
58
59      attribute1 = None
60      '''This is an attribute.
61
62      More details.
63      '''
64
65      #: This is another attribute.
66      attribute2 = None
67
68      def __init__(self):
69          '''Constructor
70
71          :parameters:
72             `arg1` : type
73                description
74          '''
75
76          self.instance_attribute = None
77          '''This is an instance attribute.
78          '''
79
80      def method(self):
81          '''Short description.
82
83          :returns: return description
84          :rtype: returned type
85          '''
86
87      def _get_property1(self):
88          '''Getter Method contains docstrings for a property
89
90          :return: property1 value
91          :rtype: property1 type
92          '''
93
94      def _set_property1(self, value):
95          '''Setter Method docstrings are ignored
96          '''
97
98      property1 = property(_get_property1, _set_property1,
99                        doc='''Override docstring here if you want''')
100
101
102Pyglet has a special role for deprecations, ``:deprecated:``.
103
104    .. list-table::
105        :header-rows: 1
106
107        * - Source
108          - Output
109        * - ``:deprecated: Do not use``
110          - .. warning:: Deprecated. Do not use
111
112
113Building
114--------
115
116The complete documentation can be generated using ``sphinx``.
117Make sure you prepare your environment as stated in :doc:`virtualenv`.
118
119To build the documentation, execute::
120
121   ./make.py docs --open
122
123.. note ::
124   Due to a bug in Sphinx, documentation generation currently only works using Python 3.x.
125
126If the build succeeds, the web pages are in ``doc/_build/html``.
127
128Optionally the standalone way to build docs is through
129``setup.py`` or ``make``.
130
131.. code:: bash
132
133    # using setup.py (output dir: _build in project root)
134    python setup.py build_sphinx
135
136    # make (make.bat for windows)
137    cd doc
138    make html
139
140HTML Theme
141----------
142
143.. Note:: The custom theme was disabled in 2019 and replaced with
144          the standard Read the Docs theme ``sphinx_rtd_theme``.
145
146The custom sphinx theme is in the ``ext/theme`` folder.
147