code-annotations 3.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- code_annotations/__init__.py +6 -0
- code_annotations/annotation_errors.py +64 -0
- code_annotations/base.py +647 -0
- code_annotations/cli.py +271 -0
- code_annotations/contrib/README.rst +8 -0
- code_annotations/contrib/config/__init__.py +14 -0
- code_annotations/contrib/config/feature_toggle_annotations.yaml +29 -0
- code_annotations/contrib/config/openedx_events_annotations.yaml +20 -0
- code_annotations/contrib/config/setting_annotations.yaml +13 -0
- code_annotations/contrib/sphinx/extensions/__init__.py +3 -0
- code_annotations/contrib/sphinx/extensions/base.py +53 -0
- code_annotations/contrib/sphinx/extensions/featuretoggles.py +137 -0
- code_annotations/contrib/sphinx/extensions/openedx_events.py +182 -0
- code_annotations/contrib/sphinx/extensions/settings.py +139 -0
- code_annotations/exceptions.py +9 -0
- code_annotations/extensions/__init__.py +3 -0
- code_annotations/extensions/base.py +166 -0
- code_annotations/extensions/javascript.py +20 -0
- code_annotations/extensions/python.py +20 -0
- code_annotations/find_django.py +460 -0
- code_annotations/find_static.py +96 -0
- code_annotations/generate_docs.py +165 -0
- code_annotations/helpers.py +182 -0
- code_annotations/report_templates/html/annotation.tpl +14 -0
- code_annotations/report_templates/html/annotation_data.tpl +8 -0
- code_annotations/report_templates/html/annotation_list.tpl +27 -0
- code_annotations/report_templates/html/base.tpl +92 -0
- code_annotations/report_templates/rst/annotation.tpl +13 -0
- code_annotations/report_templates/rst/annotation_data.tpl +8 -0
- code_annotations/report_templates/rst/annotation_group.tpl +2 -0
- code_annotations/report_templates/rst/annotation_list.tpl +34 -0
- code_annotations/report_templates/rst/base.tpl +41 -0
- code_annotations-3.1.0.dist-info/METADATA +82 -0
- code_annotations-3.1.0.dist-info/RECORD +39 -0
- code_annotations-3.1.0.dist-info/WHEEL +5 -0
- code_annotations-3.1.0.dist-info/entry_points.txt +6 -0
- code_annotations-3.1.0.dist-info/licenses/LICENSE.txt +202 -0
- code_annotations-3.1.0.dist-info/licenses/NOTICE.txt +13 -0
- code_annotations-3.1.0.dist-info/top_level.txt +1 -0
code_annotations/cli.py
ADDED
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Command line interface for code annotation tools.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
import datetime
|
|
6
|
+
import sys
|
|
7
|
+
import traceback
|
|
8
|
+
|
|
9
|
+
import click
|
|
10
|
+
|
|
11
|
+
from code_annotations.base import AnnotationConfig, ConfigurationException
|
|
12
|
+
from code_annotations.find_django import DjangoSearch
|
|
13
|
+
from code_annotations.find_static import StaticSearch
|
|
14
|
+
from code_annotations.generate_docs import ReportRenderer
|
|
15
|
+
from code_annotations.helpers import fail
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@click.group()
|
|
19
|
+
def entry_point():
|
|
20
|
+
"""
|
|
21
|
+
Top level click command for the code annotation tools.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@entry_point.command("django_find_annotations")
|
|
26
|
+
@click.option(
|
|
27
|
+
"--config_file",
|
|
28
|
+
default=".annotations",
|
|
29
|
+
help="Path to the configuration file",
|
|
30
|
+
type=click.Path(exists=True, dir_okay=False, resolve_path=True),
|
|
31
|
+
)
|
|
32
|
+
@click.option(
|
|
33
|
+
"--seed_safelist/--no_safelist",
|
|
34
|
+
default=False,
|
|
35
|
+
show_default=True,
|
|
36
|
+
help="Generate an initial safelist file based on the current Django environment.",
|
|
37
|
+
)
|
|
38
|
+
@click.option(
|
|
39
|
+
"--list_local_models/--no_list_models",
|
|
40
|
+
default=False,
|
|
41
|
+
show_default=True,
|
|
42
|
+
help="List all locally defined models (in the current repo) that require annotations.",
|
|
43
|
+
)
|
|
44
|
+
@click.option(
|
|
45
|
+
"--app_name",
|
|
46
|
+
default=None,
|
|
47
|
+
help="(Optional) App name for which coverage is generated.",
|
|
48
|
+
)
|
|
49
|
+
@click.option("--report_path", default=None, help="Location to write the report")
|
|
50
|
+
@click.option("-v", "--verbosity", count=True, help="Verbosity level (-v through -vvv)")
|
|
51
|
+
@click.option(
|
|
52
|
+
"--lint/--no_lint",
|
|
53
|
+
help="Enable or disable linting checks",
|
|
54
|
+
default=False,
|
|
55
|
+
show_default=True,
|
|
56
|
+
)
|
|
57
|
+
@click.option(
|
|
58
|
+
"--report/--no_report",
|
|
59
|
+
help="Enable or disable writing the report",
|
|
60
|
+
default=False,
|
|
61
|
+
show_default=True,
|
|
62
|
+
)
|
|
63
|
+
@click.option(
|
|
64
|
+
"--coverage/--no_coverage",
|
|
65
|
+
help="Enable or disable coverage checks",
|
|
66
|
+
default=False,
|
|
67
|
+
show_default=True,
|
|
68
|
+
)
|
|
69
|
+
def django_find_annotations(
|
|
70
|
+
config_file,
|
|
71
|
+
seed_safelist,
|
|
72
|
+
list_local_models,
|
|
73
|
+
app_name,
|
|
74
|
+
report_path,
|
|
75
|
+
verbosity,
|
|
76
|
+
lint,
|
|
77
|
+
report,
|
|
78
|
+
coverage,
|
|
79
|
+
):
|
|
80
|
+
"""
|
|
81
|
+
Subcommand for dealing with annotations in Django models.
|
|
82
|
+
"""
|
|
83
|
+
try:
|
|
84
|
+
start_time = datetime.datetime.utcnow()
|
|
85
|
+
|
|
86
|
+
if (
|
|
87
|
+
not coverage
|
|
88
|
+
and not seed_safelist
|
|
89
|
+
and not list_local_models
|
|
90
|
+
and not lint
|
|
91
|
+
and not report
|
|
92
|
+
):
|
|
93
|
+
click.echo(
|
|
94
|
+
"No actions specified. Please specify one or more of --seed_safelist, --list_local_models, "
|
|
95
|
+
"--lint, --report, or --coverage"
|
|
96
|
+
)
|
|
97
|
+
sys.exit(1)
|
|
98
|
+
|
|
99
|
+
config = AnnotationConfig(config_file, report_path, verbosity)
|
|
100
|
+
searcher = DjangoSearch(config, app_name)
|
|
101
|
+
|
|
102
|
+
# Early out if we're trying to do coverage, but a coverage target is not configured
|
|
103
|
+
if coverage and not config.coverage_target:
|
|
104
|
+
raise ConfigurationException(
|
|
105
|
+
"Please add 'coverage_target' to your configuration before running --coverage"
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
if seed_safelist:
|
|
109
|
+
searcher.seed_safelist()
|
|
110
|
+
|
|
111
|
+
if list_local_models:
|
|
112
|
+
searcher.list_local_models()
|
|
113
|
+
|
|
114
|
+
if lint or report or coverage:
|
|
115
|
+
annotated_models = searcher.search()
|
|
116
|
+
|
|
117
|
+
if lint:
|
|
118
|
+
click.echo("Performing linting checks...")
|
|
119
|
+
|
|
120
|
+
# Check grouping and choices
|
|
121
|
+
if not searcher.check_results(annotated_models):
|
|
122
|
+
click.secho("\nSearch failed due to linting errors!", fg="red")
|
|
123
|
+
click.secho("{} errors:".format(len(searcher.errors)), fg="red")
|
|
124
|
+
click.secho("---------------------------------", fg="red")
|
|
125
|
+
click.echo("\n".join(searcher.errors))
|
|
126
|
+
# If there are any errors, do not continue
|
|
127
|
+
sys.exit(1)
|
|
128
|
+
click.echo("Linting passed without errors.")
|
|
129
|
+
|
|
130
|
+
if coverage:
|
|
131
|
+
if not searcher.check_coverage():
|
|
132
|
+
# If there are any errors, do not continue
|
|
133
|
+
sys.exit(1)
|
|
134
|
+
|
|
135
|
+
click.echo("Coverage passed without errors.")
|
|
136
|
+
|
|
137
|
+
if report:
|
|
138
|
+
searcher.report(annotated_models, app_name)
|
|
139
|
+
|
|
140
|
+
annotation_count = 0
|
|
141
|
+
|
|
142
|
+
for filename in annotated_models:
|
|
143
|
+
annotation_count += len(annotated_models[filename])
|
|
144
|
+
|
|
145
|
+
elapsed = datetime.datetime.utcnow() - start_time
|
|
146
|
+
click.echo(
|
|
147
|
+
"Search found {} annotations in {} seconds.".format(
|
|
148
|
+
annotation_count, elapsed.total_seconds()
|
|
149
|
+
)
|
|
150
|
+
)
|
|
151
|
+
except Exception as exc:
|
|
152
|
+
click.echo(traceback.print_exc())
|
|
153
|
+
fail(str(exc))
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
@entry_point.command("static_find_annotations")
|
|
157
|
+
@click.option(
|
|
158
|
+
"--config_file",
|
|
159
|
+
default=".annotations",
|
|
160
|
+
help="Path to the configuration file",
|
|
161
|
+
type=click.Path(exists=True, dir_okay=False, resolve_path=True),
|
|
162
|
+
)
|
|
163
|
+
@click.option(
|
|
164
|
+
"--source_path",
|
|
165
|
+
help="Location of the source code to search",
|
|
166
|
+
type=click.Path(exists=True, dir_okay=True, resolve_path=True),
|
|
167
|
+
)
|
|
168
|
+
@click.option("--report_path", default=None, help="Location to write the report")
|
|
169
|
+
@click.option("-v", "--verbosity", count=True, help="Verbosity level (-v through -vvv)")
|
|
170
|
+
@click.option(
|
|
171
|
+
"--lint/--no_lint",
|
|
172
|
+
help="Enable or disable linting checks",
|
|
173
|
+
default=True,
|
|
174
|
+
show_default=True,
|
|
175
|
+
)
|
|
176
|
+
@click.option(
|
|
177
|
+
"--report/--no_report",
|
|
178
|
+
help="Enable or disable writing the report file",
|
|
179
|
+
default=True,
|
|
180
|
+
show_default=True,
|
|
181
|
+
)
|
|
182
|
+
def static_find_annotations(
|
|
183
|
+
config_file, source_path, report_path, verbosity, lint, report
|
|
184
|
+
):
|
|
185
|
+
"""
|
|
186
|
+
Subcommand to find annotations via static file analysis.
|
|
187
|
+
"""
|
|
188
|
+
try:
|
|
189
|
+
start_time = datetime.datetime.utcnow()
|
|
190
|
+
config = AnnotationConfig(config_file, report_path, verbosity, source_path)
|
|
191
|
+
searcher = StaticSearch(config)
|
|
192
|
+
all_results = searcher.search()
|
|
193
|
+
|
|
194
|
+
if lint:
|
|
195
|
+
click.echo("Performing linting checks...")
|
|
196
|
+
# Check grouping and choices
|
|
197
|
+
searcher.check_results(all_results)
|
|
198
|
+
|
|
199
|
+
# If there are any errors, do not generate the report
|
|
200
|
+
if searcher.errors:
|
|
201
|
+
click.secho("\nSearch failed due to linting errors!", fg="red")
|
|
202
|
+
click.secho("{} errors:".format(len(searcher.errors)), fg="red")
|
|
203
|
+
click.secho("---------------------------------", fg="red")
|
|
204
|
+
click.echo("\n".join(searcher.errors))
|
|
205
|
+
sys.exit(1)
|
|
206
|
+
click.echo("Linting passed without errors.")
|
|
207
|
+
|
|
208
|
+
if report:
|
|
209
|
+
click.echo("Writing report...")
|
|
210
|
+
report_filename = searcher.report(all_results)
|
|
211
|
+
click.echo(f"Report written to {report_filename}.")
|
|
212
|
+
|
|
213
|
+
elapsed = datetime.datetime.utcnow() - start_time
|
|
214
|
+
annotation_count = 0
|
|
215
|
+
|
|
216
|
+
for filename in all_results:
|
|
217
|
+
annotation_count += len(all_results[filename])
|
|
218
|
+
|
|
219
|
+
click.echo(f"Search found {annotation_count} annotations in {elapsed}.")
|
|
220
|
+
|
|
221
|
+
except Exception as exc:
|
|
222
|
+
click.echo(traceback.print_exc())
|
|
223
|
+
fail(str(exc))
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
@entry_point.command("generate_docs")
|
|
227
|
+
@click.option(
|
|
228
|
+
"--config_file",
|
|
229
|
+
default=".annotations",
|
|
230
|
+
help="Path to the configuration file",
|
|
231
|
+
type=click.Path(exists=True, dir_okay=False),
|
|
232
|
+
)
|
|
233
|
+
@click.option("-v", "--verbosity", count=True, help="Verbosity level (-v through -vvv)")
|
|
234
|
+
@click.argument("report_files", type=click.File("r"), nargs=-1)
|
|
235
|
+
def generate_docs(config_file, verbosity, report_files):
|
|
236
|
+
"""
|
|
237
|
+
Generate documentation from a code annotations report.
|
|
238
|
+
"""
|
|
239
|
+
start_time = datetime.datetime.utcnow()
|
|
240
|
+
|
|
241
|
+
try:
|
|
242
|
+
config = AnnotationConfig(config_file, verbosity)
|
|
243
|
+
|
|
244
|
+
if not report_files:
|
|
245
|
+
raise ConfigurationException(
|
|
246
|
+
"No report files provided. Please provide one or more report files to generate docs from."
|
|
247
|
+
)
|
|
248
|
+
|
|
249
|
+
for key in (
|
|
250
|
+
"report_template_dir",
|
|
251
|
+
"rendered_report_dir",
|
|
252
|
+
"rendered_report_format",
|
|
253
|
+
"rendered_report_source_link_prefix",
|
|
254
|
+
):
|
|
255
|
+
if not getattr(config, key):
|
|
256
|
+
raise ConfigurationException(f"No {key} key in {config_file}")
|
|
257
|
+
|
|
258
|
+
config.echo(
|
|
259
|
+
"Rendering the following reports: \n{}".format(
|
|
260
|
+
"\n".join([r.name for r in report_files])
|
|
261
|
+
)
|
|
262
|
+
)
|
|
263
|
+
|
|
264
|
+
renderer = ReportRenderer(config, report_files)
|
|
265
|
+
renderer.render()
|
|
266
|
+
|
|
267
|
+
elapsed = datetime.datetime.utcnow() - start_time
|
|
268
|
+
click.echo(f"Report rendered in {elapsed.total_seconds()} seconds.")
|
|
269
|
+
except Exception as exc:
|
|
270
|
+
click.echo(traceback.print_exc())
|
|
271
|
+
fail(str(exc))
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
config and tools
|
|
2
|
+
================
|
|
3
|
+
|
|
4
|
+
This directory will contain annotation configurations that can be shared across repositories, as well as shared tools based on these configurations, such as Sphinx extensions that can be used to document certain types of annotations.
|
|
5
|
+
|
|
6
|
+
These custom configurations should be kept separate from the general annotations tool in /code_annotations.
|
|
7
|
+
|
|
8
|
+
For more details, see the ADR in docs/decisions/0001-config-and-tools.rst.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Expose contrib configuration file paths as Python variables, for use in 3rd-party utilities.
|
|
3
|
+
"""
|
|
4
|
+
import importlib.resources
|
|
5
|
+
import os
|
|
6
|
+
|
|
7
|
+
FEATURE_TOGGLE_ANNOTATIONS_CONFIG_PATH = importlib.resources.files(
|
|
8
|
+
"code_annotations") / os.path.join("contrib", "config", "feature_toggle_annotations.yaml")
|
|
9
|
+
|
|
10
|
+
SETTING_ANNOTATIONS_CONFIG_PATH = importlib.resources.files(
|
|
11
|
+
"code_annotations") / os.path.join("contrib", "config", "setting_annotations.yaml")
|
|
12
|
+
|
|
13
|
+
OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH = importlib.resources.files(
|
|
14
|
+
"code_annotations") / os.path.join("contrib", "config", "openedx_events_annotations.yaml")
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# This code-annotations configuration file supports OEP-17, Feature Toggles.
|
|
2
|
+
|
|
3
|
+
source_path: ./
|
|
4
|
+
report_path: reports
|
|
5
|
+
safelist_path: .annotation_safe_list.yml
|
|
6
|
+
coverage_target: 50.0
|
|
7
|
+
annotations:
|
|
8
|
+
feature_toggle:
|
|
9
|
+
# See annotation format documentation: https://edx-toggles.readthedocs.io/en/latest/how_to/documenting_new_feature_toggles.html
|
|
10
|
+
- ".. toggle_name:":
|
|
11
|
+
- ".. toggle_implementation:":
|
|
12
|
+
choices: [WaffleFlag, WaffleSwitch, CourseWaffleFlag, ExperimentWaffleFlag, SettingToggle, SettingDictToggle, ConfigurationModel, DjangoSetting]
|
|
13
|
+
- ".. toggle_default:":
|
|
14
|
+
- ".. toggle_description:":
|
|
15
|
+
- ".. toggle_use_cases:":
|
|
16
|
+
choices: [temporary, circuit_breaker, vip, opt_out, opt_in, open_edx]
|
|
17
|
+
- ".. toggle_creation_date:":
|
|
18
|
+
- ".. toggle_removal_ticket:":
|
|
19
|
+
optional: true
|
|
20
|
+
- ".. toggle_target_removal_date:":
|
|
21
|
+
optional: true
|
|
22
|
+
- ".. toggle_warning:":
|
|
23
|
+
optional: true
|
|
24
|
+
- ".. toggle_tickets:":
|
|
25
|
+
optional: true
|
|
26
|
+
extensions:
|
|
27
|
+
python:
|
|
28
|
+
- py
|
|
29
|
+
rst_template: doc.rst.j2
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# This code-annotations configuration file supports openedx-events
|
|
2
|
+
|
|
3
|
+
source_path: ./
|
|
4
|
+
report_path: reports
|
|
5
|
+
safelist_path: .annotation_safe_list.yml
|
|
6
|
+
coverage_target: 100.0
|
|
7
|
+
annotations:
|
|
8
|
+
feature_toggle:
|
|
9
|
+
# See annotation format documentation: https://docs.openedx.org/projects/openedx-events/en/latest/reference/in-line-code-annotations-for-an-event.html
|
|
10
|
+
- ".. event_type:":
|
|
11
|
+
- ".. event_name:":
|
|
12
|
+
- ".. event_description:":
|
|
13
|
+
- ".. event_data:":
|
|
14
|
+
- ".. event_key_field:":
|
|
15
|
+
- ".. event_trigger_repository:":
|
|
16
|
+
- ".. event_warning:":
|
|
17
|
+
extensions:
|
|
18
|
+
python:
|
|
19
|
+
- py
|
|
20
|
+
rst_template: doc.rst.j2
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
source_path: ./
|
|
2
|
+
report_path: reports
|
|
3
|
+
safelist_path: .annotation_safe_list.yml
|
|
4
|
+
annotations:
|
|
5
|
+
setting:
|
|
6
|
+
- ".. setting_name:":
|
|
7
|
+
- ".. setting_default:":
|
|
8
|
+
- ".. setting_description:":
|
|
9
|
+
- ".. setting_warning:":
|
|
10
|
+
optional: true
|
|
11
|
+
extensions:
|
|
12
|
+
python:
|
|
13
|
+
- py
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Base utilities for building annotation-based Sphinx extensions.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
from code_annotations.base import AnnotationConfig
|
|
7
|
+
from code_annotations.find_static import StaticSearch
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def find_annotations(source_path, config_path, group_by_key):
|
|
11
|
+
"""
|
|
12
|
+
Find the feature toggles as defined in the configuration file.
|
|
13
|
+
|
|
14
|
+
Return:
|
|
15
|
+
toggles (dict): feature toggles indexed by name.
|
|
16
|
+
"""
|
|
17
|
+
config = AnnotationConfig(
|
|
18
|
+
config_path, verbosity=-1, source_path_override=source_path
|
|
19
|
+
)
|
|
20
|
+
search = StaticSearch(config)
|
|
21
|
+
all_results = search.search()
|
|
22
|
+
toggles = {}
|
|
23
|
+
for filename in all_results:
|
|
24
|
+
for annotations in search.iter_groups(all_results[filename]):
|
|
25
|
+
current_entry = {}
|
|
26
|
+
for annotation in annotations:
|
|
27
|
+
key = annotation["annotation_token"]
|
|
28
|
+
value = annotation["annotation_data"]
|
|
29
|
+
if key == group_by_key:
|
|
30
|
+
toggle_name = value
|
|
31
|
+
toggles[toggle_name] = current_entry
|
|
32
|
+
current_entry["filename"] = filename
|
|
33
|
+
current_entry["line_number"] = annotation["line_number"]
|
|
34
|
+
else:
|
|
35
|
+
current_entry[key] = value
|
|
36
|
+
|
|
37
|
+
return toggles
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def quote_value(value):
|
|
41
|
+
"""
|
|
42
|
+
Quote a Python object if it is string-like.
|
|
43
|
+
"""
|
|
44
|
+
if value in ("True", "False", "None"):
|
|
45
|
+
return str(value)
|
|
46
|
+
try:
|
|
47
|
+
float(value)
|
|
48
|
+
return str(value)
|
|
49
|
+
except ValueError:
|
|
50
|
+
pass
|
|
51
|
+
if isinstance(value, str):
|
|
52
|
+
return f'"{value}"'
|
|
53
|
+
return str(value)
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Sphinx extension for viewing feature toggle annotations.
|
|
3
|
+
"""
|
|
4
|
+
import os
|
|
5
|
+
|
|
6
|
+
from docutils import nodes
|
|
7
|
+
from sphinx.util.docutils import SphinxDirective
|
|
8
|
+
|
|
9
|
+
from code_annotations.contrib.config import FEATURE_TOGGLE_ANNOTATIONS_CONFIG_PATH
|
|
10
|
+
|
|
11
|
+
from .base import find_annotations, quote_value
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def find_feature_toggles(source_path):
|
|
15
|
+
"""
|
|
16
|
+
Find the feature toggles as defined in the configuration file.
|
|
17
|
+
|
|
18
|
+
Return:
|
|
19
|
+
toggles (dict): feature toggles indexed by name.
|
|
20
|
+
"""
|
|
21
|
+
return find_annotations(
|
|
22
|
+
source_path, FEATURE_TOGGLE_ANNOTATIONS_CONFIG_PATH, ".. toggle_name:"
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class FeatureToggles(SphinxDirective):
|
|
27
|
+
"""
|
|
28
|
+
Sphinx directive to list the feature toggles in a single documentation page.
|
|
29
|
+
|
|
30
|
+
Use this directive as follows::
|
|
31
|
+
|
|
32
|
+
.. featuretoggles::
|
|
33
|
+
|
|
34
|
+
This directive supports the following configuration parameters:
|
|
35
|
+
|
|
36
|
+
- ``featuretoggles_source_path``: absolute path to the repository file tree. E.g:
|
|
37
|
+
|
|
38
|
+
featuretoggles_source_path = os.path.join(os.path.dirname(__file__), "..", "..")
|
|
39
|
+
|
|
40
|
+
- ``featuretoggles_repo_url``: Github repository where the code is hosted. E.g:
|
|
41
|
+
|
|
42
|
+
featuretoggles_repo_url = "https://github.com/openedx/myrepo"
|
|
43
|
+
|
|
44
|
+
- ``featuretoggles_repo_version``: current version of the git repository. E.g:
|
|
45
|
+
|
|
46
|
+
import git
|
|
47
|
+
try:
|
|
48
|
+
repo = git.Repo(search_parent_directories=True)
|
|
49
|
+
featuretoggles_repo_version = repo.head.object.hexsha
|
|
50
|
+
except git.InvalidGitRepositoryError:
|
|
51
|
+
featuretoggles_repo_version = "master"
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
required_arguments = 0
|
|
55
|
+
optional_arguments = 0
|
|
56
|
+
option_spec = {}
|
|
57
|
+
|
|
58
|
+
def run(self):
|
|
59
|
+
"""
|
|
60
|
+
Public interface of the Directive class.
|
|
61
|
+
|
|
62
|
+
Return:
|
|
63
|
+
nodes (list): nodes to be appended to the resulting document.
|
|
64
|
+
"""
|
|
65
|
+
return list(self.iter_nodes())
|
|
66
|
+
|
|
67
|
+
def iter_nodes(self):
|
|
68
|
+
"""
|
|
69
|
+
Iterate on the docutils nodes generated by this directive.
|
|
70
|
+
"""
|
|
71
|
+
toggles = find_feature_toggles(self.env.config.featuretoggles_source_path)
|
|
72
|
+
for toggle_name in sorted(toggles):
|
|
73
|
+
toggle = toggles[toggle_name]
|
|
74
|
+
toggle_default_value = toggle.get(".. toggle_default:", "Not defined")
|
|
75
|
+
toggle_default_node = nodes.literal(text=quote_value(toggle_default_value))
|
|
76
|
+
toggle_section = nodes.section("", ids=[f"featuretoggle-{toggle_name}"])
|
|
77
|
+
toggle_section += nodes.title(text=toggle_name, ids=[f"name-{toggle_name}"])
|
|
78
|
+
toggle_section += nodes.paragraph(
|
|
79
|
+
"", "Default: ", toggle_default_node, ids=[f"default-{toggle_name}"]
|
|
80
|
+
)
|
|
81
|
+
toggle_section += nodes.paragraph(
|
|
82
|
+
"",
|
|
83
|
+
"Source: ",
|
|
84
|
+
nodes.reference(
|
|
85
|
+
text="{} (line {})".format(
|
|
86
|
+
toggle["filename"], toggle["line_number"]
|
|
87
|
+
),
|
|
88
|
+
refuri="{}/blob/{}/{}#L{}".format(
|
|
89
|
+
self.env.config.featuretoggles_repo_url,
|
|
90
|
+
self.env.config.featuretoggles_repo_version,
|
|
91
|
+
toggle["filename"],
|
|
92
|
+
toggle["line_number"],
|
|
93
|
+
),
|
|
94
|
+
),
|
|
95
|
+
ids=[f"source-{toggle_name}"],
|
|
96
|
+
)
|
|
97
|
+
toggle_section += nodes.paragraph(
|
|
98
|
+
text=f'Desc: {toggle.get(".. toggle_description:", "NaN")}',
|
|
99
|
+
ids=[f"description-{toggle_name}"],
|
|
100
|
+
)
|
|
101
|
+
if toggle.get(".. toggle_warning:") not in (None, "None", "n/a", "N/A"):
|
|
102
|
+
toggle_section += nodes.warning(
|
|
103
|
+
"", nodes.paragraph("", toggle[".. toggle_warning:"]), ids=[f"warning-{toggle_name}"]
|
|
104
|
+
)
|
|
105
|
+
optional_attrs = [
|
|
106
|
+
"creation_date",
|
|
107
|
+
"target_removal_date",
|
|
108
|
+
"implementation",
|
|
109
|
+
"use_cases",
|
|
110
|
+
]
|
|
111
|
+
for opt in optional_attrs:
|
|
112
|
+
if toggle.get(f".. toggle_{opt}:") not in (None, "None", "n/a", "N/A"):
|
|
113
|
+
toggle_section += nodes.paragraph(
|
|
114
|
+
text=f'{opt.title().replace("_", " ")}: {toggle[f".. toggle_{opt}:"]}',
|
|
115
|
+
ids=[f"{opt}-{toggle_name}"],
|
|
116
|
+
)
|
|
117
|
+
yield toggle_section
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def setup(app):
|
|
121
|
+
"""
|
|
122
|
+
Declare the Sphinx extension.
|
|
123
|
+
"""
|
|
124
|
+
app.add_config_value(
|
|
125
|
+
"featuretoggles_source_path",
|
|
126
|
+
os.path.abspath(".."),
|
|
127
|
+
"env",
|
|
128
|
+
)
|
|
129
|
+
app.add_config_value("featuretoggles_repo_url", "", "env")
|
|
130
|
+
app.add_config_value("featuretoggles_repo_version", "master", "env")
|
|
131
|
+
app.add_directive("featuretoggles", FeatureToggles)
|
|
132
|
+
|
|
133
|
+
return {
|
|
134
|
+
"version": "0.1",
|
|
135
|
+
"parallel_read_safe": True,
|
|
136
|
+
"parallel_write_safe": True,
|
|
137
|
+
}
|