1"""Configuration file for Sphinx."""
2import sys
3import os
4from subprocess import check_output
5
6sys.path.insert(0, os.path.abspath('..'))
7sys.path.insert(0, os.path.abspath('.'))
8
9# Fake import to avoid actually loading CFFI and the PortAudio library
10import fake__sounddevice
11sys.modules['_sounddevice'] = sys.modules['fake__sounddevice']
12
13extensions = [
14    'sphinx.ext.autodoc',
15    'sphinx.ext.autosummary',
16    'sphinx.ext.intersphinx',
17    'sphinx.ext.viewcode',
18    'sphinx.ext.napoleon',  # support for NumPy-style docstrings
19    'sphinx_last_updated_by_git',
20]
21
22autoclass_content = 'init'
23autodoc_member_order = 'bysource'
24
25napoleon_google_docstring = False
26napoleon_numpy_docstring = True
27napoleon_include_private_with_doc = False
28napoleon_include_special_with_doc = False
29napoleon_use_admonition_for_examples = False
30napoleon_use_admonition_for_notes = False
31napoleon_use_admonition_for_references = False
32napoleon_use_ivar = False
33napoleon_use_param = False
34napoleon_use_rtype = False
35
36intersphinx_mapping = {
37    'python': ('https://docs.python.org/3/', None),
38    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
39}
40
41master_doc = 'index'
42
43authors = 'Matthias Geier'
44project = 'python-sounddevice'
45
46try:
47    release = check_output(['git', 'describe', '--tags', '--always'])
48    release = release.decode().strip()
49except Exception:
50    release = '<unknown>'
51
52try:
53    today = check_output(['git', 'show', '-s', '--format=%ad', '--date=short'])
54    today = today.decode().strip()
55except Exception:
56    today = '<unknown date>'
57
58default_role = 'any'
59
60nitpicky = True
61
62html_theme = 'insipid'
63html_theme_options = {
64}
65html_title = project + ', version ' + release
66html_favicon = 'favicon.svg'
67html_domain_indices = False
68html_show_copyright = False
69html_copy_source = False
70html_permalinks_icon = '§'
71htmlhelp_basename = 'python-sounddevice'
72
73latex_elements = {
74'papersize': 'a4paper',
75#'preamble': '',
76'printindex': '',
77}
78latex_documents = [('index', 'python-sounddevice.tex', project, authors, 'howto')]
79latex_show_urls = 'footnote'
80latex_domain_indices = False
81
82
83def gh_example_role(rolename, rawtext, text, lineno, inliner,
84                    options={}, content=()):
85    from docutils import nodes, utils
86    github_url = 'https://github.com/spatialaudio/python-sounddevice'
87    base_url = github_url + '/blob/' + release + '/examples/%s'
88    text = utils.unescape(text)
89    full_url = base_url % text
90    pnode = nodes.reference(internal=False, refuri=full_url)
91    pnode += nodes.literal(text, text, classes=['file'])
92    return [pnode], []
93
94
95def setup(app):
96    app.add_role('gh-example', gh_example_role)
97