DOC: gh-example role

Author: mgeier

doc/conf.py

@@ -75,3 +75,19 @@
 latex_documents = [('index', 'python-sounddevice.tex', project, authors, 'howto')]
 latex_show_urls = 'footnote'
 latex_domain_indices = False
+
+
+def gh_example_role(rolename, rawtext, text, lineno, inliner,
+                    options={}, content=()):
+    from docutils import nodes, utils
+    github_url = 'https://github.com/spatialaudio/python-sounddevice'
+    base_url = github_url + '/blob/' + release + '/examples/%s'
+    text = utils.unescape(text)
+    full_url = base_url % text
+    pnode = nodes.reference(internal=False, refuri=full_url)
+    pnode += nodes.literal(text, text, classes=['file'])
+    return [pnode], []
+
+
+def setup(app):
+    app.add_role('gh-example', gh_example_role)

doc/examples.rst

@@ -3,69 +3,69 @@
 Play a Sound File
 -----------------
 
-:download:`play_file.py <../examples/play_file.py>`
+:gh-example:`play_file.py`
 
 .. literalinclude:: ../examples/play_file.py
 
 Play a Very Long Sound File
 ---------------------------
 
-:download:`play_long_file.py <../examples/play_long_file.py>`
+:gh-example:`play_long_file.py`
 
 .. literalinclude:: ../examples/play_long_file.py
 
 Play a Web Stream
 -----------------
 
-:download:`play_stream.py <../examples/play_stream.py>`
+:gh-example:`play_stream.py`
 
 .. literalinclude:: ../examples/play_stream.py
 
 Play a Sine Signal
 ------------------
 
-:download:`play_sine.py <../examples/play_sine.py>`
+:gh-example:`play_sine.py`
 
 .. literalinclude:: ../examples/play_sine.py
 
 Input to Output Pass-Through
 ----------------------------
 
-:download:`wire.py <../examples/wire.py>`
+:gh-example:`wire.py`
 
 .. literalinclude:: ../examples/wire.py
 
 Plot Microphone Signal(s) in Real-Time
 --------------------------------------
 
-:download:`plot_input.py <../examples/plot_input.py>`
+:gh-example:`plot_input.py`
 
 .. literalinclude:: ../examples/plot_input.py
 
 Real-Time Text-Mode Spectrogram
 -------------------------------
 
-:download:`spectrogram.py <../examples/spectrogram.py>`
+:gh-example:`spectrogram.py`
 
 .. literalinclude:: ../examples/spectrogram.py
 
 Recording with Arbitrary Duration
 ---------------------------------
 
-:download:`rec_unlimited.py <../examples/rec_unlimited.py>`
+:gh-example:`rec_unlimited.py`
 
 .. literalinclude:: ../examples/rec_unlimited.py
 
 Using a stream in an `asyncio` coroutine
 ----------------------------------------
 
-:download:`asyncio_coroutines.py <../examples/asyncio_coroutines.py>`
+:gh-example:`asyncio_coroutines.py`
 
 .. literalinclude:: ../examples/asyncio_coroutines.py
 
 Creating an `asyncio` generator for audio blocks
 ------------------------------------------------
 
-:download:`asyncio_generators.py <../examples/asyncio_generators.py>`
+:gh-example:`asyncio_generators.py`
 
 .. literalinclude:: ../examples/asyncio_generators.py