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
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Contains functionality for turning YAML reports into human-readable documentation.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
import collections
|
|
6
|
+
import datetime
|
|
7
|
+
import os
|
|
8
|
+
|
|
9
|
+
import jinja2
|
|
10
|
+
import yaml
|
|
11
|
+
from slugify import slugify
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class ReportRenderer:
|
|
15
|
+
"""
|
|
16
|
+
Generates human readable documentation from YAML reports.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
def __init__(self, config, report_files):
|
|
20
|
+
"""
|
|
21
|
+
Initialize a ReportRenderer.
|
|
22
|
+
|
|
23
|
+
Args:
|
|
24
|
+
config: An AnnotationConfig object
|
|
25
|
+
report_files: A list of files to combine and report on
|
|
26
|
+
"""
|
|
27
|
+
self.config = config
|
|
28
|
+
self.echo = self.config.echo
|
|
29
|
+
self.report_files = report_files
|
|
30
|
+
self.create_time = datetime.datetime.now(tz=datetime.timezone.utc)
|
|
31
|
+
self.full_report = self._aggregate_reports()
|
|
32
|
+
|
|
33
|
+
self.jinja_environment = jinja2.Environment(
|
|
34
|
+
autoescape=False,
|
|
35
|
+
loader=jinja2.FileSystemLoader(self.config.report_template_dir),
|
|
36
|
+
lstrip_blocks=True,
|
|
37
|
+
trim_blocks=True
|
|
38
|
+
)
|
|
39
|
+
self.top_level_template = self.jinja_environment.get_template('annotation_list.tpl')
|
|
40
|
+
self.all_choices = []
|
|
41
|
+
self.group_mapping = {}
|
|
42
|
+
|
|
43
|
+
for token in self.config.choices:
|
|
44
|
+
self.all_choices.extend(self.config.choices[token])
|
|
45
|
+
|
|
46
|
+
for group_name in self.config.groups:
|
|
47
|
+
for token in self.config.groups[group_name]:
|
|
48
|
+
self.group_mapping[token] = group_name
|
|
49
|
+
|
|
50
|
+
def _add_report_file_to_full_report(self, report_file, report):
|
|
51
|
+
"""
|
|
52
|
+
Add a specified report file to a report.
|
|
53
|
+
|
|
54
|
+
Args:
|
|
55
|
+
report_file:
|
|
56
|
+
report:
|
|
57
|
+
|
|
58
|
+
Returns:
|
|
59
|
+
|
|
60
|
+
"""
|
|
61
|
+
loaded_report = yaml.safe_load(report_file)
|
|
62
|
+
|
|
63
|
+
for filename in loaded_report:
|
|
64
|
+
trimmed_filename = filename
|
|
65
|
+
for prefix in self.config.trim_filename_prefixes:
|
|
66
|
+
if filename.startswith(prefix):
|
|
67
|
+
trimmed_filename = filename[len(prefix):]
|
|
68
|
+
break
|
|
69
|
+
|
|
70
|
+
if filename in report:
|
|
71
|
+
for loaded_annotation in loaded_report[filename]:
|
|
72
|
+
found = False
|
|
73
|
+
for report_annotation in report[filename]:
|
|
74
|
+
index_keys = ('line_number', 'annotation_token', 'annotation_data')
|
|
75
|
+
|
|
76
|
+
if all(loaded_annotation[k] == report_annotation[k] for k in index_keys):
|
|
77
|
+
report_annotation.update(loaded_annotation)
|
|
78
|
+
found = True
|
|
79
|
+
break
|
|
80
|
+
|
|
81
|
+
if not found:
|
|
82
|
+
report[trimmed_filename].append(loaded_annotation)
|
|
83
|
+
else:
|
|
84
|
+
report[trimmed_filename] = loaded_report[filename]
|
|
85
|
+
|
|
86
|
+
def _aggregate_reports(self):
|
|
87
|
+
"""
|
|
88
|
+
Combine all of the given report files into a single report object.
|
|
89
|
+
"""
|
|
90
|
+
report = collections.defaultdict(list)
|
|
91
|
+
|
|
92
|
+
# Combine report files into a single dict. If there are duplicate annotations, make sure we have the superset
|
|
93
|
+
# of data.
|
|
94
|
+
for r in self.report_files:
|
|
95
|
+
self._add_report_file_to_full_report(r, report)
|
|
96
|
+
|
|
97
|
+
return report
|
|
98
|
+
|
|
99
|
+
def _write_doc_file(self, doc_title, doc_filename, doc_data):
|
|
100
|
+
"""
|
|
101
|
+
Write out a single report file with the given data. This is rendered using the configured top level template.
|
|
102
|
+
|
|
103
|
+
Args:
|
|
104
|
+
doc_title: Title to use for the document.
|
|
105
|
+
doc_filename: Filename to write to.
|
|
106
|
+
doc_data: Dict of reporting data to use, in the {'file name': [list, of, annotations,]} style.
|
|
107
|
+
"""
|
|
108
|
+
full_doc_filename = os.path.join(
|
|
109
|
+
self.config.rendered_report_dir,
|
|
110
|
+
slugify(doc_filename)
|
|
111
|
+
)
|
|
112
|
+
|
|
113
|
+
full_doc_filename += self.config.rendered_report_file_extension
|
|
114
|
+
|
|
115
|
+
self.echo.echo_v(f'Writing {full_doc_filename}')
|
|
116
|
+
|
|
117
|
+
with open(full_doc_filename, 'w') as output:
|
|
118
|
+
output.write(self.top_level_template.render(
|
|
119
|
+
doc_title=doc_title,
|
|
120
|
+
create_time=self.create_time,
|
|
121
|
+
report=doc_data,
|
|
122
|
+
all_choices=self.all_choices,
|
|
123
|
+
all_annotations=self.config.annotation_tokens,
|
|
124
|
+
group_mapping=self.group_mapping,
|
|
125
|
+
slugify=slugify,
|
|
126
|
+
source_link_prefix=self.config.rendered_report_source_link_prefix,
|
|
127
|
+
third_party_package_location=self.config.third_party_package_location,
|
|
128
|
+
))
|
|
129
|
+
|
|
130
|
+
def _generate_per_choice_docs(self):
|
|
131
|
+
"""
|
|
132
|
+
Generate a page of documentation for each configured annotation choice.
|
|
133
|
+
"""
|
|
134
|
+
for choice in self.all_choices:
|
|
135
|
+
choice_report = collections.defaultdict(list)
|
|
136
|
+
for filename in self.full_report:
|
|
137
|
+
for annotation in self.full_report[filename]:
|
|
138
|
+
if isinstance(annotation['annotation_data'], list) and choice in annotation['annotation_data']:
|
|
139
|
+
choice_report[filename].append(annotation)
|
|
140
|
+
|
|
141
|
+
self._write_doc_file(f"All References to Choice '{choice}'", f'choice_{choice}', choice_report)
|
|
142
|
+
|
|
143
|
+
def _generate_per_annotation_docs(self):
|
|
144
|
+
"""
|
|
145
|
+
Generate a page of documentation for each configured annotation.
|
|
146
|
+
"""
|
|
147
|
+
for annotation in self.config.annotation_tokens:
|
|
148
|
+
annotation_report = collections.defaultdict(list)
|
|
149
|
+
for filename in self.full_report:
|
|
150
|
+
for report_annotation in self.full_report[filename]:
|
|
151
|
+
if report_annotation['annotation_token'] == annotation:
|
|
152
|
+
annotation_report[filename].append(report_annotation)
|
|
153
|
+
|
|
154
|
+
self._write_doc_file(
|
|
155
|
+
f"All References to Annotation '{annotation}'", f'annotation_{annotation}', annotation_report
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
def render(self):
|
|
159
|
+
"""
|
|
160
|
+
Perform the rendering of all documentation using the configured Jinja2 templates.
|
|
161
|
+
"""
|
|
162
|
+
# Generate the top level list of all annotations
|
|
163
|
+
self._write_doc_file("Complete Annotation List", 'index', self.full_report)
|
|
164
|
+
self._generate_per_choice_docs()
|
|
165
|
+
self._generate_per_annotation_docs()
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Helpers for code_annotations scripts.
|
|
3
|
+
"""
|
|
4
|
+
import os
|
|
5
|
+
import re
|
|
6
|
+
import sys
|
|
7
|
+
from io import StringIO
|
|
8
|
+
from pprint import pprint
|
|
9
|
+
|
|
10
|
+
import click
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def fail(msg):
|
|
14
|
+
"""
|
|
15
|
+
Log the message and exit.
|
|
16
|
+
|
|
17
|
+
Args:
|
|
18
|
+
msg: Message to log
|
|
19
|
+
"""
|
|
20
|
+
click.secho(msg, fg="red")
|
|
21
|
+
sys.exit(1)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class VerboseEcho:
|
|
25
|
+
"""
|
|
26
|
+
Helper to handle verbosity-dependent logging.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
verbosity = 1
|
|
30
|
+
|
|
31
|
+
def __call__(self, output, **kwargs):
|
|
32
|
+
"""
|
|
33
|
+
Echo the given output regardless of verbosity level.
|
|
34
|
+
|
|
35
|
+
This is just a convenience method to avoid lots of `self.echo.echo()`.
|
|
36
|
+
|
|
37
|
+
Args:
|
|
38
|
+
output: Text to output
|
|
39
|
+
kwargs: Any additional keyword args to pass to click.echo
|
|
40
|
+
"""
|
|
41
|
+
self.echo(output, **kwargs)
|
|
42
|
+
|
|
43
|
+
def set_verbosity(self, verbosity):
|
|
44
|
+
"""
|
|
45
|
+
Override the default verbosity level.
|
|
46
|
+
|
|
47
|
+
Args:
|
|
48
|
+
verbosity: The verbosity level to set to
|
|
49
|
+
kwargs: Any additional keyword args to pass to click.echo
|
|
50
|
+
"""
|
|
51
|
+
self.verbosity = verbosity
|
|
52
|
+
self.echo_v(f"Verbosity level set to {verbosity}")
|
|
53
|
+
|
|
54
|
+
def echo(self, output, verbosity_level=0, **kwargs):
|
|
55
|
+
"""
|
|
56
|
+
Echo the given output, if over the verbosity threshold.
|
|
57
|
+
|
|
58
|
+
Args:
|
|
59
|
+
output: Text to output
|
|
60
|
+
verbosity_level: Only output if our verbosity level is >= this.
|
|
61
|
+
kwargs: Any additional keyword args to pass to click.echo
|
|
62
|
+
"""
|
|
63
|
+
if verbosity_level <= self.verbosity:
|
|
64
|
+
click.secho(output, **kwargs)
|
|
65
|
+
|
|
66
|
+
def echo_v(self, output, **kwargs):
|
|
67
|
+
"""
|
|
68
|
+
Echo the given output if verbosity level is >= 1.
|
|
69
|
+
|
|
70
|
+
Args:
|
|
71
|
+
output: Text to output
|
|
72
|
+
kwargs: Any additional keyword args to pass to click.echo
|
|
73
|
+
"""
|
|
74
|
+
self.echo(output, 1, **kwargs)
|
|
75
|
+
|
|
76
|
+
def echo_vv(self, output, **kwargs):
|
|
77
|
+
"""
|
|
78
|
+
Echo the given output if verbosity level is >= 2.
|
|
79
|
+
|
|
80
|
+
Args:
|
|
81
|
+
output: Text to output
|
|
82
|
+
kwargs: Any additional keyword args to pass to click.echo
|
|
83
|
+
"""
|
|
84
|
+
self.echo(output, 2, **kwargs)
|
|
85
|
+
|
|
86
|
+
def echo_vvv(self, output, **kwargs):
|
|
87
|
+
"""
|
|
88
|
+
Echo the given output if verbosity level is >= 3.
|
|
89
|
+
|
|
90
|
+
Args:
|
|
91
|
+
output: Text to output
|
|
92
|
+
kwargs: Any additional keyword args to pass to click.echo
|
|
93
|
+
"""
|
|
94
|
+
self.echo(output, 3, **kwargs)
|
|
95
|
+
|
|
96
|
+
def pprint(self, data, indent=4, verbosity_level=0):
|
|
97
|
+
"""
|
|
98
|
+
Pretty-print some data with the given verbosity level.
|
|
99
|
+
"""
|
|
100
|
+
formatted = StringIO()
|
|
101
|
+
pprint(data, indent=indent, stream=formatted)
|
|
102
|
+
formatted.seek(0)
|
|
103
|
+
self.echo(formatted.read(), verbosity_level=verbosity_level)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def clean_abs_path(filename_to_clean, parent_path):
|
|
107
|
+
"""
|
|
108
|
+
Safely strips the parent path from the given filename, leaving only the relative path.
|
|
109
|
+
|
|
110
|
+
Args:
|
|
111
|
+
filename_to_clean: Input filename
|
|
112
|
+
parent_path: Path to remove from the input
|
|
113
|
+
|
|
114
|
+
Returns:
|
|
115
|
+
Updated path
|
|
116
|
+
"""
|
|
117
|
+
# If we are operating on only one file we don't know what to strip off here,
|
|
118
|
+
# just return the whole thing.
|
|
119
|
+
if filename_to_clean == parent_path:
|
|
120
|
+
return os.path.basename(filename_to_clean)
|
|
121
|
+
return os.path.relpath(filename_to_clean, parent_path)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def get_annotation_regex(annotation_regexes):
|
|
125
|
+
"""
|
|
126
|
+
Return the full regex to search inside comments for configured annotations.
|
|
127
|
+
|
|
128
|
+
A successful match against the regex will return two groups of interest: 'token'
|
|
129
|
+
and 'data'.
|
|
130
|
+
|
|
131
|
+
This regular expression supports annotation tokens that span multiple lines. To do
|
|
132
|
+
so, prefix each line after the first by at least two leading spaces. E.g:
|
|
133
|
+
|
|
134
|
+
.. pii: First line
|
|
135
|
+
second line
|
|
136
|
+
|
|
137
|
+
Unfortunately, the indenting spaces will find their way to the content of the "token" group.
|
|
138
|
+
|
|
139
|
+
Args:
|
|
140
|
+
annotation_regexes: List of re.escaped annotation tokens to search for.
|
|
141
|
+
|
|
142
|
+
Returns:
|
|
143
|
+
Regex ready for searching comments for annotations.
|
|
144
|
+
"""
|
|
145
|
+
annotation_regex = r"""
|
|
146
|
+
(?P<space>[\ \t]*) # Leading empty spaces
|
|
147
|
+
(?P<token>{tokens}) # Python format string that will be replaced with a
|
|
148
|
+
# regex, escaped and then or-joined to make a list
|
|
149
|
+
# of the annotation tokens we're looking for
|
|
150
|
+
# Ex: (\.\.\ pii\:\:|\.\.\ pii\_types\:\:)
|
|
151
|
+
(?P<data> # Captured annotation data
|
|
152
|
+
(?: # non-capture mode
|
|
153
|
+
. # any non-newline character
|
|
154
|
+
| # or new line of multi-line annotation data
|
|
155
|
+
(?: # non-capture mode
|
|
156
|
+
\n{{1,}} # at least one newline,
|
|
157
|
+
(?P=space) # followed by as much space as the prefix,
|
|
158
|
+
(?P<indent>\ {{2,}}) # at least two spaces,
|
|
159
|
+
(?=[^\ ]) # and a non-space character (look-ahead)
|
|
160
|
+
(?!{tokens}) # that does not match any of the token regexes
|
|
161
|
+
) #
|
|
162
|
+
)* # any number of times
|
|
163
|
+
)
|
|
164
|
+
"""
|
|
165
|
+
annotation_regex = annotation_regex.format(tokens='|'.join(annotation_regexes))
|
|
166
|
+
return re.compile(annotation_regex, flags=re.VERBOSE)
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def clean_annotation(token, data):
|
|
170
|
+
"""
|
|
171
|
+
Clean annotation token and data by stripping all trailing/prefix empty spaces.
|
|
172
|
+
|
|
173
|
+
Args:
|
|
174
|
+
token (str)
|
|
175
|
+
data (str)
|
|
176
|
+
|
|
177
|
+
Returns:
|
|
178
|
+
(str, str): Tuple of cleaned token, data
|
|
179
|
+
"""
|
|
180
|
+
token = token.strip()
|
|
181
|
+
data = data.strip()
|
|
182
|
+
return token, data
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{% if is_third_party %}
|
|
2
|
+
{# no links for third party code since we don't know where to link to #}
|
|
3
|
+
{% if annotation.extra and annotation.extra.object_id %}
|
|
4
|
+
{{ annotation.extra.object_id }} {% if annotation.line_number > 0 %}line {{ annotation.line_number }}{% endif %}: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
|
|
5
|
+
{% else %}
|
|
6
|
+
{% if loop.changed(annotation.line_number)%}{{ filename }}:{{ annotation.line_number }}<br />{% endif %}:
|
|
7
|
+
{{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
|
|
8
|
+
{% endif %}
|
|
9
|
+
|
|
10
|
+
{% elif annotation.extra and annotation.extra.object_id %}
|
|
11
|
+
<a href="{{ source_link_prefix }}{{ filename }}#L{{ annotation.line_number }}" target="_blank">{{ annotation.extra.object_id }} {% if annotation.line_number > 0 %}line {{ annotation.line_number }}{% endif %}</a>: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
|
|
12
|
+
{% else %}
|
|
13
|
+
<a href="{{ source_link_prefix }}{{ filename }}#L{{ annotation.line_number }}" target="_blank">`{{ filename }}:{{ annotation.line_number }}: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
|
|
14
|
+
{% endif %}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
{% if annotation.annotation_data is sequence and annotation.annotation_data is not string %}
|
|
2
|
+
{% for a in annotation.annotation_data %}
|
|
3
|
+
<a href="choice-{{ slugify(a) }}.html">{{ a }}</a>{% if not loop.last %}, {% endif %}
|
|
4
|
+
{% endfor %}
|
|
5
|
+
|
|
6
|
+
{% else %}
|
|
7
|
+
{{ annotation.annotation_data }}
|
|
8
|
+
{% endif %}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
{% extends "base.tpl" %}
|
|
2
|
+
{% block content %}
|
|
3
|
+
Annotations found in {{ report|length }} files.
|
|
4
|
+
|
|
5
|
+
{% for filename in report %}
|
|
6
|
+
{% set is_third_party = third_party_package_location in filename %}
|
|
7
|
+
|
|
8
|
+
<h2 id="file-{{ slugify(filename) }}">{{ filename }}</h2>
|
|
9
|
+
<div class="file-annotations">
|
|
10
|
+
{{ report[filename]|length }} annotations {% if is_third_party %}(installed package){% endif %}<br />
|
|
11
|
+
</div>
|
|
12
|
+
|
|
13
|
+
{% for annotation in report[filename] %}
|
|
14
|
+
{% if loop.changed(annotation.report_group_id) %}
|
|
15
|
+
{% if not loop.first %}</ul></div>{% endif %}
|
|
16
|
+
<div class="group-annotations"><ul>
|
|
17
|
+
{% endif %}
|
|
18
|
+
<li>{% include 'annotation.tpl' %}</li>
|
|
19
|
+
{% if loop.last %}
|
|
20
|
+
</ul></div>
|
|
21
|
+
{% endif %}
|
|
22
|
+
{% endfor %}
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
{% endfor %}
|
|
26
|
+
|
|
27
|
+
{% endblock %}
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
<html>
|
|
2
|
+
<head>
|
|
3
|
+
<title>{{ doc_title }}</title>
|
|
4
|
+
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
5
|
+
<style>
|
|
6
|
+
body {
|
|
7
|
+
font-family: 'Trebuchet MS', sans-serif;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
.title {
|
|
11
|
+
text-align: center;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
.table {
|
|
15
|
+
display: table;
|
|
16
|
+
border-spacing: 12px;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
.row {
|
|
20
|
+
display: table-row;
|
|
21
|
+
margin-bottom: 0;
|
|
22
|
+
margin-top: 0;
|
|
23
|
+
width: 100%;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
.cell1 {
|
|
27
|
+
display: table-cell;
|
|
28
|
+
width: 20%;
|
|
29
|
+
margin-right: 1%;
|
|
30
|
+
border: 1px solid #ccc;
|
|
31
|
+
margin 12px;
|
|
32
|
+
background-color: #ffffee;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
.cell2 {
|
|
36
|
+
display: table-cell;
|
|
37
|
+
width: 79%;
|
|
38
|
+
margin-right: 1%;
|
|
39
|
+
margin 12px;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
.group-annotations {
|
|
43
|
+
border: 1px solid #ccc;
|
|
44
|
+
margin: 10px;
|
|
45
|
+
}
|
|
46
|
+
</style>
|
|
47
|
+
</head>
|
|
48
|
+
<body>
|
|
49
|
+
<h1 class="title">{{ doc_title }}</h1>
|
|
50
|
+
|
|
51
|
+
<div class="table">
|
|
52
|
+
<div class="row">
|
|
53
|
+
<div class="cell1">
|
|
54
|
+
<h3><a href="index.html">Home</a></h3>
|
|
55
|
+
|
|
56
|
+
<h3>Annotations</h3>
|
|
57
|
+
|
|
58
|
+
<ul>
|
|
59
|
+
{% for a in all_annotations %}
|
|
60
|
+
<li><a href="annotation-{{ slugify(a) }}.html">annotation_{{ slugify(a) }}</a></li>
|
|
61
|
+
{% endfor %}
|
|
62
|
+
</ul>
|
|
63
|
+
|
|
64
|
+
<h3>Choices</h3>
|
|
65
|
+
|
|
66
|
+
<ul>
|
|
67
|
+
{% for choice in all_choices %}
|
|
68
|
+
<li><a href="choice-{{ slugify(choice) }}.html">choice_{{ slugify(choice) }}</a></li>
|
|
69
|
+
{% endfor %}
|
|
70
|
+
</ul>
|
|
71
|
+
</div>
|
|
72
|
+
<div class="cell2">
|
|
73
|
+
<h2>Files in this page</h2>
|
|
74
|
+
<ul>
|
|
75
|
+
{% for filename in report %}
|
|
76
|
+
<li><a href="#file-{{ slugify(filename) }}">{{ filename }}</a></li>
|
|
77
|
+
{% endfor %}
|
|
78
|
+
</ul>
|
|
79
|
+
|
|
80
|
+
{% block content %}{% endblock %}
|
|
81
|
+
</div>
|
|
82
|
+
</div>
|
|
83
|
+
</div>
|
|
84
|
+
{% block footer %}
|
|
85
|
+
<div class="footer">
|
|
86
|
+
<br /><br />
|
|
87
|
+
<hr />
|
|
88
|
+
Built at {{ create_time.strftime('%Y-%m-%d %H:%M:%S %Z') }}
|
|
89
|
+
</div>
|
|
90
|
+
{% endblock %}
|
|
91
|
+
</body>
|
|
92
|
+
</html>
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
{% if is_third_party %}
|
|
2
|
+
{# no links for third party code since we don't know where to link to #}
|
|
3
|
+
{% if annotation.extra and annotation.extra.object_id %}
|
|
4
|
+
{{ annotation.extra.object_id }} {% if annotation.line_number > 0 %}line {{ annotation.line_number }}{% endif %}: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
|
|
5
|
+
{% else %}
|
|
6
|
+
{{ filename }}:{{ annotation.line_number }}: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
|
|
7
|
+
{% endif %}
|
|
8
|
+
|
|
9
|
+
{% elif annotation.extra and annotation.extra.object_id %}
|
|
10
|
+
`{{ annotation.extra.object_id }} {% if annotation.line_number > 0 %}line {{ annotation.line_number }}{% endif %} <{{ source_link_prefix }}{{ filename }}#L{{ annotation.line_number }}>`_: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
|
|
11
|
+
{% else %}
|
|
12
|
+
`{{ filename }}:{{ annotation.line_number }} <{{ source_link_prefix }}{{ filename }}#L{{ annotation.line_number }}>`_: {{ annotation.annotation_token }} {% include "annotation_data.tpl" %}
|
|
13
|
+
{% endif %}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
{% if annotation.annotation_data is sequence and annotation.annotation_data is not string %}
|
|
2
|
+
{% for a in annotation.annotation_data %}
|
|
3
|
+
choice_{{ slugify(a) }}_{% if not loop.last %}, {% endif %}
|
|
4
|
+
{% endfor %}
|
|
5
|
+
|
|
6
|
+
{% else %}
|
|
7
|
+
{{ annotation.annotation_data }}
|
|
8
|
+
{% endif %}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
{% extends "base.tpl" %}
|
|
2
|
+
{% block content %}
|
|
3
|
+
Annotations found in {{ report|length }} files.
|
|
4
|
+
|
|
5
|
+
{% for filename in report %}
|
|
6
|
+
{% set is_third_party = third_party_package_location in filename %}
|
|
7
|
+
|
|
8
|
+
{{ filename }}
|
|
9
|
+
{{ "-" * filename|length }}
|
|
10
|
+
|
|
11
|
+
.. note:: {{ report[filename]|length }} annotations {% if is_third_party %}(installed package){% endif %}
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
{% for annotation in report[filename] %}
|
|
15
|
+
{% if annotation.report_group_id %}
|
|
16
|
+
{% if loop.changed(annotation.report_group_id) %}
|
|
17
|
+
{% include 'annotation_group.tpl' %}
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
{% endif %}
|
|
21
|
+
* {% include 'annotation.tpl' %}
|
|
22
|
+
|
|
23
|
+
{% else %}
|
|
24
|
+
{% if loop.changed(annotation.report_group_id) %}
|
|
25
|
+
|
|
26
|
+
{% endif %}
|
|
27
|
+
* {% include 'annotation.tpl' %}
|
|
28
|
+
|
|
29
|
+
{% endif %}
|
|
30
|
+
{% endfor %}
|
|
31
|
+
|
|
32
|
+
{% endfor %}
|
|
33
|
+
|
|
34
|
+
{% endblock %}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
{{ "#" * doc_title|length }}
|
|
2
|
+
{{ doc_title }}
|
|
3
|
+
{{ "#" * doc_title|length }}
|
|
4
|
+
|
|
5
|
+
.. sidebar:: Table of Contents
|
|
6
|
+
|
|
7
|
+
`Home <index.rst>`_
|
|
8
|
+
|
|
9
|
+
Annotations
|
|
10
|
+
|
|
11
|
+
{% for a in all_annotations %}
|
|
12
|
+
* annotation_{{ slugify(a) }}_
|
|
13
|
+
{% endfor %}
|
|
14
|
+
|
|
15
|
+
Choices
|
|
16
|
+
|
|
17
|
+
{% for choice in all_choices %}
|
|
18
|
+
* choice_{{ slugify(choice) }}_
|
|
19
|
+
{% endfor %}
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
.. contents::
|
|
23
|
+
|
|
24
|
+
{% block content %}{% endblock %}
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
{# backlinks for all choices #}
|
|
28
|
+
{% for choice in all_choices %}
|
|
29
|
+
.. _choice_{{ slugify(choice) }}: {{ slugify('choice_' + choice) + '.rst' }}
|
|
30
|
+
{% endfor %}
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
{# backlinks for all annotations #}
|
|
34
|
+
{% for annotation in all_annotations %}
|
|
35
|
+
.. _annotation_{{ slugify(annotation) }}: {{ slugify('annotation_' + annotation) + '.rst' }}
|
|
36
|
+
{% endfor %}
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
{% block footer %}
|
|
40
|
+
Built at {{ create_time.strftime('%Y-%m-%d %H:%M:%S %Z') }}
|
|
41
|
+
{% endblock %}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: code-annotations
|
|
3
|
+
Version: 3.1.0
|
|
4
|
+
Summary: Extensible tools for parsing annotations in codebases
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
Project-URL: Homepage, https://github.com/openedx/code-annotations
|
|
7
|
+
Classifier: Development Status :: 3 - Alpha
|
|
8
|
+
Classifier: Framework :: Django
|
|
9
|
+
Classifier: Framework :: Django :: 4.2
|
|
10
|
+
Classifier: Framework :: Django :: 5.2
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Natural Language :: English
|
|
13
|
+
Classifier: Programming Language :: Python
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Requires-Python: >=3.12
|
|
17
|
+
Description-Content-Type: text/x-rst
|
|
18
|
+
License-File: LICENSE.txt
|
|
19
|
+
License-File: NOTICE.txt
|
|
20
|
+
Requires-Dist: click
|
|
21
|
+
Requires-Dist: pyyaml
|
|
22
|
+
Requires-Dist: Jinja2
|
|
23
|
+
Requires-Dist: stevedore
|
|
24
|
+
Requires-Dist: python-slugify
|
|
25
|
+
Provides-Extra: django
|
|
26
|
+
Requires-Dist: Django>=4.2; extra == "django"
|
|
27
|
+
Dynamic: license-file
|
|
28
|
+
|
|
29
|
+
code-annotations
|
|
30
|
+
=============================
|
|
31
|
+
|
|
32
|
+
Extensible tools for parsing annotations in codebases
|
|
33
|
+
|
|
34
|
+
Overview
|
|
35
|
+
--------
|
|
36
|
+
|
|
37
|
+
This package provides configurable and extensible tools for parsing and
|
|
38
|
+
summarizing annotations in a wide range of codebases. Originally intended for
|
|
39
|
+
annotating code which stores personally identifiable information (PII), these
|
|
40
|
+
tools are optimized for that use case but can be generalized for other types of
|
|
41
|
+
annotations.
|
|
42
|
+
|
|
43
|
+
Additionally, a logically separate part of this repository will contain specific annotation configurations and supporting tools, such as Sphinx extensions for documenting specific annotation types. See the ``contrib`` folder.
|
|
44
|
+
|
|
45
|
+
Documentation
|
|
46
|
+
-------------
|
|
47
|
+
|
|
48
|
+
The full documentation is at https://code-annotations.readthedocs.org.
|
|
49
|
+
|
|
50
|
+
License
|
|
51
|
+
-------
|
|
52
|
+
|
|
53
|
+
The code in this repository is licensed under the Apache Software License 2.0 unless
|
|
54
|
+
otherwise noted.
|
|
55
|
+
|
|
56
|
+
Please see ``LICENSE.txt`` for details.
|
|
57
|
+
|
|
58
|
+
How To Contribute
|
|
59
|
+
-----------------
|
|
60
|
+
|
|
61
|
+
Contributions are very welcome.
|
|
62
|
+
|
|
63
|
+
Please read `How To Contribute <https://github.com/openedx/.github/blob/master/CONTRIBUTING.md>`_ for details.
|
|
64
|
+
|
|
65
|
+
PR description template should be automatically applied if you are sending PR from github interface; otherwise you
|
|
66
|
+
can find it it at `PULL_REQUEST_TEMPLATE.md <https://github.com/openedx/code-annotations/blob/master/.github/PULL_REQUEST_TEMPLATE.md>`_
|
|
67
|
+
|
|
68
|
+
Issue report template should be automatically applied if you are sending it from github UI as well; otherwise you
|
|
69
|
+
can find it at `ISSUE_TEMPLATE.md <https://github.com/openedx/code-annotations/blob/master/.github/ISSUE_TEMPLATE.md>`_
|
|
70
|
+
|
|
71
|
+
Reporting Security Issues
|
|
72
|
+
-------------------------
|
|
73
|
+
|
|
74
|
+
Please do not report security issues in public. Please email security@openedx.org.
|
|
75
|
+
|
|
76
|
+
Getting Help
|
|
77
|
+
------------
|
|
78
|
+
|
|
79
|
+
Have a question about this repository, or about Open edX in general? Please
|
|
80
|
+
refer to this `list of resources`_ if you need any assistance.
|
|
81
|
+
|
|
82
|
+
.. _list of resources: https://open.edx.org/getting-help
|