-
Notifications
You must be signed in to change notification settings - Fork 13
/
conf.py
170 lines (138 loc) · 5.37 KB
/
conf.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
# type: ignore
from __future__ import annotations
import enum
import inspect
import os
import re
import sys
from urllib.request import urlopen
sys.path.insert(0, os.path.abspath(".."))
import m2r2
from pyflp._base import ( # noqa
EventEnum,
EventProp,
IterProp,
ModelBase,
NestedProp,
StructProp,
)
BITLY_LINK = re.compile(r"!\[.*\]\((https://bit\.ly/[A-z0-9]*)\)")
NEW_IN_FL = re.compile(r"\*New in FL Studio v([^\*]*)\*[\.:](.*)")
EVENT_ID_DOC = re.compile(r"([0-9\.]*)\+")
FL_BADGE = (
"https://img.shields.io/badge/FL-%s+-5f686d?labelColor=ff7629&style=flat-square"
)
GHUC_PREFIX = "https://raw.githubusercontent.com/demberto/PyFLP/master/docs/"
project = "PyFLP"
copyright = "2022, demberto"
author = "demberto"
release = "2.0.0a0"
extensions = [
"hoverxref.extension",
"m2r2",
"sphinx_copybutton",
"sphinx_design",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.coverage",
"sphinx.ext.duration",
"sphinx.ext.intersphinx",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
"sphinx_toolbox",
"sphinx_toolbox.github",
"sphinx_toolbox.sidebar_links",
]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
html_theme = "furo"
autodoc_inherit_docstrings = False
autodoc_default_options = {
"undoc-members": True,
"exclude-members": "INTERNAL_NAME",
"no-value": True,
}
needs_sphinx = "5.0"
hoverxref_auto_ref = True
coverage_ignore_pyobjects = ["[A-Z][A-z0-9]*Event"]
napoleon_preprocess_types = True
napoleon_attr_annotations = True
html_permalinks_icon = "<span>#</span>"
github_username = author
github_repository = project
def badge_flstudio(app, what, name, obj, options, lines):
for line in lines:
if name.split(".")[-2].endswith("ID"): # Event ID member
match = EVENT_ID_DOC.fullmatch(line)
else:
match = NEW_IN_FL.fullmatch(line)
if match is not None:
groups = tuple(
filter(
lambda group: group != "",
map(lambda group: group.strip(), match.groups()),
)
)
if len(groups) == 1:
lines.insert(0, f".. image:: {FL_BADGE % groups[0]}")
lines.insert(1, "")
elif len(groups) == 2:
grid = f"""
.. figure:: {FL_BADGE % groups[0]}
:align: left
:alt: New in FL Studio v{groups[0]}
{groups[1].strip()}
"""
lines[:0] = grid.splitlines() # https://stackoverflow.com/a/25855473
lines.remove(line)
def transform_image_links(app, what, name, obj, options, lines):
"""Convert Bit.ly markdown image links to local reStructuredText ones."""
for idx, line in enumerate(lines):
match = BITLY_LINK.fullmatch(line)
if match is not None:
url = urlopen(match[1]).geturl()
lines[idx] = f".. image:: {url.replace(GHUC_PREFIX, '', 1)}"
def add_annotations(app, what, name, obj, options, signature, return_annotation):
if what == "class" and issubclass(obj, ModelBase):
annotations = {}
for name_, type in vars(obj).items():
if isinstance(obj, (IterProp, NestedProp)):
annotations[name_] = type._type
elif hasattr(type, "__orig_class__"):
annotations[name_] = type.__orig_class__.__args__[0]
if isinstance(type, (EventProp, StructProp)):
annotations[name_] |= None
if hasattr(obj, "__annotations__"):
obj.__annotations__.update(annotations)
else:
obj.__annotations__ = annotations
def autodoc_markdown(app, what, name, obj, options, lines):
newlines = m2r2.convert("\n".join(lines)).splitlines()
lines.clear()
lines.extend(newlines)
def remove_model_signature(app, what, name, obj, options, signature, return_annotation):
"""Removes the :func:`ModelBase.__init__` args from the docstrings.
It's an implementation detail, and only clutters the docs.
"""
if what == "class" and issubclass(obj, ModelBase):
return ("", return_annotation)
def remove_enum_signature(app, what, name, obj, options, signature, return_annotation):
"""Removes erroneous :attr:`signature` = '(value)' for `enum.Enum` subclasses."""
if inspect.isclass(obj) and issubclass(obj, enum.Enum): # Event ID class
return ("", return_annotation)
def include_obsolete_ids(app, what, name, obj, skip, options):
"""Includes obsolete / undocumented (prefixed with a `_`) event IDs."""
if isinstance(obj, EventEnum): # EventID member
return False
def show_model_dunders(app, what, name, obj, skip, options):
"""ModelBase subclasses show these dunders regardless of any settings."""
if name in ("__getitem__", "__setitem__", "__iter__", "__len__", "__index__"):
return False
def setup(app):
app.connect("autodoc-process-docstring", badge_flstudio)
app.connect("autodoc-process-docstring", transform_image_links)
app.connect("autodoc-process-docstring", autodoc_markdown)
app.connect("autodoc-process-signature", add_annotations)
app.connect("autodoc-process-signature", remove_model_signature)
app.connect("autodoc-process-signature", remove_enum_signature)
app.connect("autodoc-skip-member", include_obsolete_ids)
app.connect("autodoc-skip-member", show_model_dunders)