Skip to content

Commit 47b343e

Browse files
pushfoopushfoo
authored
Sound and performance doc rework (#2316)
* Use currentmodule to fix + shorten cross-refs in sound.rst * Fix typos in text and cross-refs * Replace longer pyglet Player reference with a substitution * Centralize pymunk and Chipmunk2D links into rst_prolog * Add label as link target for pymunk examples * Reorganize and rewrite performance page * Add diagram example and cross-refs to performance tips page * Move sound performance info to performance page
1 parent eb85958 commit 47b343e

File tree

8 files changed

+589
-276
lines changed

8 files changed

+589
-276
lines changed

‎arcade/pymunk_physics_engine.py‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,18 +39,14 @@ class PymunkException(Exception):
3939
class PymunkPhysicsEngine:
4040
"""An Arcade-specific adapter for Pymunk.
4141
42-
.. _Pymunk: https://www.pymunk.org/en/latest/index.html
43-
.. _Chipmunk2D: https://chipmunk-physics.net/
44-
.. _CONTRIBUTING.md: https://github.com/pythonarcade/arcade/blob/development/CONTRIBUTING.md
45-
4642
`Pymunk`_ is itself a Python adapter for the professional-grade
4743
`Chipmunk2D`_ engine. However, Arcade's ``PymunkPhysicsEngine``
4844
and its doc are currently in need of improvement.
4945
5046
.. note:: Arcade would welcome assistance with improving it.
5147
5248
If you are interested, please see Arcade's
53-
`CONTRIBUTING.md`_.
49+
`CONTRIBUTING.md <CONTRIBUTING.md: https://github.com/pythonarcade/arcade/blob/development/CONTRIBUTING.md>`_
5450
5551
Args:
5652
gravity:

‎arcade/sound.py‎

Lines changed: 38 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ class Sound:
4141
please see:
4242
4343
* :ref:`sound-loading-modes-streaming`
44-
* The py:class:`pyglet.media.codes.base.StreamingSource` class used
44+
* The :py:class:`pyglet.media.codecs.base.StreamingSource` class used
4545
internally
4646
4747
To learn about cross-platform loading and file format concerns,
@@ -90,18 +90,12 @@ def play(
9090
loop: bool = False,
9191
speed: float = 1.0,
9292
) -> media.Player:
93-
"""Try to play this :py:class:`Sound` and return a :py:class:`~pyglet.media.player.Player`.
93+
"""Try to play this :py:class:`Sound` and return a |pyglet Player|.
9494
95-
.. important:: Any :py:class:`Sound` with ``streaming=True`` loses features!
95+
.. important:: A :py:class:`Sound` with ``streaming=True`` loses features!
9696
97-
``loop`` will not work and simultaneous playbacks raise
98-
a :py:class:`RuntimeError`.
99-
100-
See the following to learn more about the keywords and restrictions:
101-
102-
* :py:class:`Sound`
103-
* :ref:`sound-advanced-playback-change-aspects-ongoing`
104-
* :ref:`sound-advanced-playback-change-aspects-new`
97+
Neither ``loop`` nor simultaneous playbacks will work. See
98+
:py;class:`Sound` and :ref:`sound-loading-modes`.
10599
106100
Args:
107101
volume: Volume (``0.0`` is silent, ``1.0`` is loudest).
@@ -110,6 +104,8 @@ def play(
110104
loop: ``True`` attempts to restart playback after finishing.
111105
speed: Change the speed (and pitch) of the sound. Default speed is
112106
``1.0``.
107+
Returns:
108+
A |pyglet Player| for this playback.
113109
"""
114110
if isinstance(self.source, media.StreamingSource) and self.source.is_player_source:
115111
raise RuntimeError(
@@ -151,14 +147,14 @@ def _on_player_eos():
151147
return player
152148

153149
def stop(self, player: media.Player) -> None:
154-
"""Permanently stop and :py:meth:`~pyglet.media.player.Player.delete` ``player``.
150+
"""Stop and :py:meth:`~pyglet.media.player.Player.delete` ``player``.
155151
156-
All references in the :py:class:`pyglet.media.Source` player table
157-
will be deleted.
152+
All references to it in the internal table for
153+
:py:class:`pyglet.media.Source` will be deleted.
158154
159155
Args:
160-
player: A pyglet :py:class:`~pyglet.media.player.Player`
161-
returned from :func:`play_sound` or :py:meth:`Sound.play`.
156+
player: A pyglet |pyglet Player| from :func:`play_sound`
157+
or :py:meth:`Sound.play`.
162158
"""
163159
player.pause()
164160
player.delete()
@@ -179,9 +175,8 @@ def is_playing(self, player: media.Player) -> bool:
179175
"""``True`` if ``player`` is currently playing, otherwise ``False``.
180176
181177
Args:
182-
player: A pyglet :py:class:`~pyglet.media.player.Player`
183-
returned from :py:meth:`Sound.play <.Sound.play>` or
184-
:func:`play_sound`.
178+
player: A |pyglet Player| from :func:`play_sound` or
179+
:py:meth:`Sound.play`.
185180
186181
Returns:
187182
``True`` if the passed pyglet player is playing.
@@ -192,9 +187,8 @@ def get_volume(self, player: media.Player) -> float:
192187
"""Get the current volume.
193188
194189
Args:
195-
player: A pyglet :py:class:`~pyglet.media.player.Player`
196-
returned from :py:meth:`Sound.play <.Sound.play>` or
197-
:func:`play_sound`.
190+
player: A |pyglet Player| from :func:`play_sound` or
191+
:py:meth:`Sound.play`.
198192
Returns:
199193
A volume between ``0.0`` (silent) and ``1.0`` (full volume).
200194
"""
@@ -205,8 +199,8 @@ def set_volume(self, volume: float, player: media.Player) -> None:
205199
206200
Args:
207201
volume: Floating point volume. 0 is silent, 1 is full.
208-
player: A pyglet :py:class:`~pyglet.media.player.Player`
209-
returned from :func:`play_sound` or :py:meth:`Sound.play`.
202+
player: A |pyglet Player| from :func:`play_sound` or
203+
:py:meth:`Sound.play`.
210204
"""
211205
player.volume = volume
212206

@@ -215,18 +209,19 @@ def get_stream_position(self, player: media.Player) -> float:
215209
zero when it is done playing.
216210
217211
Args:
218-
player: Player returned from :func:`play_sound`.
212+
player: A |pyglet Player| from :func:`play_sound` or
213+
:py:meth:`Sound.play`.
219214
"""
220215
return player.time
221216

222217

223218
def load_sound(path: str | Path, streaming: bool = False) -> Sound:
224219
"""Load a file as a :py:class:`Sound` data object.
225220
226-
.. important:: Using ``streaming=True`` disables certain features!
221+
.. important:: A :py:class:`Sound` with ``streaming=True`` loses features!
227222
228-
These include looping and multiple playbacks. Please
229-
see :py:class:`Sound` to learn more.
223+
Neither ``loop`` nor simultaneous playbacks will work. See
224+
:py;class:`Sound` and :ref:`sound-loading-modes`.
230225
231226
Args:
232227
path: a path which may be prefixed with a
@@ -261,18 +256,20 @@ def play_sound(
261256
loop: bool = False,
262257
speed: float = 1.0,
263258
) -> media.Player | None:
264-
"""Try to play the ``sound`` and return a :py:class:`~pyglet.media.player.Player`.
259+
"""Try to play the ``sound`` and return a |pyglet Player|.
265260
266-
.. note:: The ``sound`` **must** be a :py:class:`Sound` object!
261+
The ``sound`` must be a loaded :py:class:`Sound` object. If you
262+
pass a path or :py:class:`str`, the function will raise a
263+
:py:class:`TypeError.`
267264
268-
See the following to load audio from file paths:
265+
.. important:: A :py:class:`Sound` with ``streaming=True`` loses features!
269266
270-
* :ref:`sound-basics-loading`
271-
* :ref:`sound-loading-modes`
272-
* :py:func:`load_sound`
273-
* :py:class:`Sound`
267+
Neither ``loop`` nor simultaneous playbacks will work. See
268+
:py;class:`Sound` and :ref:`sound-loading-modes`.
274269
275270
The output and return value depend on whether playback succeeded:
271+
.. # Note: substitutions don't really work inside tables, so the
272+
.. # pyglet player below is left as a normal class cross-reference.
276273
277274
.. list-table::
278275
:header-rows: 1
@@ -289,21 +286,11 @@ def play_sound(
289286
- N/A
290287
- A pyglet :py:class:`~pyglet.media.player.Player`
291288
292-
See the following to learn more:
293-
294-
* :ref:`sound-basics-sound_vs_player`
295-
* :ref:`sound-advanced-playback`
296-
297-
.. important:: Any :py:class:`Sound` with ``streaming=True`` loses features!
298-
299-
``loop`` will not work and simultaneous playbacks raise
300-
a :py:class:`RuntimeError`.
301-
302289
To learn more about the ``streaming`` keyword and restrictions, please see:
303290
304291
* :py:class:`Sound`
305-
* :ref:`sound-advanced-playback-change-aspects-ongoing`
306-
* :ref:`sound-advanced-playback-change-aspects-new`
292+
* :ref:`sound-intermediate-playback-change-aspects-ongoing`
293+
* :ref:`sound-intermediate-playback-change-aspects-new`
307294
308295
Args:
309296
sound: A :py:class:`Sound` instance or ``None``.
@@ -315,9 +302,8 @@ def play_sound(
315302
values higher than ``1.0`` raise the pitch.
316303
317304
Returns:
318-
A :py:class:`pyglet.media.Player` instance for the playback or
305+
A |pyglet Player| instance for this playback or
319306
``None`` if playback failed.
320-
321307
"""
322308
if sound is None:
323309
logger.warning("Unable to play sound, no data passed in.")
@@ -338,12 +324,11 @@ def play_sound(
338324

339325

340326
def stop_sound(player: media.Player) -> None:
341-
"""Stop a pyglet player for a which is currently playing.
327+
"""Stop and delete a |pyglet Player| which is currently playing.
342328
343329
Args:
344-
player: A pyglet :py:class:`~pyglet.media.player.Player`
345-
returned from :py:meth:`Sound.play <.Sound.play>` or
346-
:func:`play_sound`.
330+
player: A pyglet |pyglet Player| from :py:func:`play_sound`
331+
or :py:meth:`Sound.play`.
347332
"""
348333

349334
if not isinstance(player, media.Player):

‎doc/conf.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
#!/usr/bin/env python
22
"""Sphinx configuration file"""
33
from functools import cache
4+
from textwrap import dedent
45
from typing import Any, NamedTuple
56
import docutils.nodes
67
import os
@@ -175,6 +176,18 @@
175176
'pymunk': ('https://www.pymunk.org/en/latest/', None),
176177
}
177178

179+
180+
# These will be joined as one block and prepended to every source file.
181+
# Substitutions for |version| and |release| are predefined by Sphinx.
182+
rst_prolog = dedent(f"""
183+
.. _Pymunk: https://www.pymunk.org/en/latest/index.html
184+
185+
.. _Chipmunk2D: https://chipmunk-physics.net/
186+
187+
.. |pyglet Player| replace:: pyglet :py:class:`~pyglet.media.player.Player`
188+
""".strip())
189+
190+
178191
def strip_init_return_typehint(app, what, name, obj, options, signature, return_annotation):
179192
# Prevent a the `-> None` annotation from appearing after classes.
180193
# This annotation comes from the `__init__`, but it renders on the class,

‎doc/example_code/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -660,6 +660,8 @@ Grid-Based Games
660660
Advanced
661661
--------
662662

663+
.. _example-code-pymunk:
664+
663665
Using PyMunk for Physics
664666
^^^^^^^^^^^^^^^^^^^^^^^^
665667

‎doc/programming_guide/images/spatial_hash_grid_mockup.png‎

9.54 KB
Loading

0 commit comments

Comments
 (0)