Hello,
While reviewing the docstrings in clock.py, I wanted to make a change to
the following docstring:
class Clock(_ClockBase):
def __init__(self, fps_limit=None,
time_function=_default_time_function):
"""Initialise a Clock, with optional framerate limit and custom
time function.
:Parameters:
`fps_limit` : float
If not None, the maximum allowable framerate. Defaults
to None. Deprecated in pyglet 1.2.
`time_function` : function
Function to return the elapsed time of the application,
in seconds. Defaults to time.time, but can be replaced
to allow for easy time dilation effects or game pausing.
"""
The `fps_limit` is deprecated and I wanted to use the sphinx directive ..
deprecated:: instead. But together with the :Parameters: heading, it does
not play nice once rendered. The code for dealing with the :Parameters: is
a pyglet self-made extension found in doc/ext/docstrings.py.
The original idea was certainly good, but today there is a much better and
more robust solution, name sphinx.ext.napoleon
<http://www.sphinx-doc.org/en/stable/ext/napoleon.html>. It allows to have
good looking docstring and to render them nicely too. It's quite similar to
pyglet own extension but it plays nicely with directives like ..
deprecated::
How would you feel about using Napoleon extension? We don't have to change
everything at once. We can just add the napoleon extension to the pyglet
extension. Napoleon would only kick-in if you would write the docstring
this way:
"""Class for calculating and limiting framerate.
It is also used for calling scheduled functions.
Args:
fps_limit (float): If not None, the maximum allowable framerate.
Defaults to ``None``.
.. deprecated:: 1.2
time_function (function): Function to return the elapsed time of the
application, in seconds. Defaults to ``time.time``, but can be
replaced to allow for easy time dilation effects or game pausing.
"""
I tried building pyglet doc and didn't notice any problems enabling
Napoleon's extension. If you want to try, you just need to edit
doc/conf.py. On line 110, change add to extensions list napoleon ext like
this:
extensions = ['sphinx.ext.autodoc',
'ext.docstrings',
'sphinx.ext.inheritance_diagram',
'sphinx.ext.todo',
'sphinx.ext.napoleon']
Daniel
--
You received this message because you are subscribed to the Google Groups
"pyglet-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/pyglet-users.
For more options, visit https://groups.google.com/d/optout.
