Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit fcac8d1

Browse files
add line dropper, tests and docs
1 parent 107587a commit fcac8d1

File tree

4 files changed

+86
-6
lines changed

4 files changed

+86
-6
lines changed

‎README.md‎

Lines changed: 56 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,15 @@ within the test, ready for rendering in the docs.
3636

3737
## install
3838
Something like:
39-
`git clone ARMmbed/snippet`
40-
41-
Then:
42-
`pip install -e path/to/snippet`
39+
```
40+
git clone ARMmbed/snippet
41+
pip install -e path/to/snippet
42+
```
43+
or directly (with `pip`>10 environment variables can be unpacked):
44+
```
45+
python -m pip install -U pip>10
46+
pip install git+https://${GH_TOKEN}@github.com/ARMmbed/snippet.git#egg=snippet
47+
```
4348

4449
## configure
4550
Place a config file in the [toml format](https://github.com/toml-lang/toml)
@@ -173,3 +178,50 @@ Some of the checks include:
173178
- Tag open / close matches (avoiding nested examples or cloaks)
174179
- Examples left unterminated
175180
- Indents reducing beyond the start level for the current example
181+
182+
## notable config options
183+
184+
Any parameter in the default configuration can be overridden.
185+
186+
Some notable entries include:
187+
188+
- `language_name` passed to the output template; can improve markdown rendering
189+
in syntax-aware renderers
190+
- `drop_lines` for removing entire lines containing these exact matches
191+
- `replacements` for globally replacing exact matches
192+
193+
```python
194+
# IO
195+
project_root = '.' # the project root used for relative IO paths (set by commandline)
196+
input_glob = 'tests/example/*.py'
197+
output_append = True # if the output file exists, append to it
198+
output_dir = '.'
199+
output_file_name_template = '{{name}}.md' # a mustache template for the output file name
200+
write_attempts = 3 # number of retries when writing output files
201+
202+
# Language and style
203+
language_name = 'python'
204+
comment_prefix = '# '
205+
comment_suffix = ''
206+
# a mustache template for each file (triple braces important for code literals, no escaping)
207+
output_template = '```{{language_name}}\n{{comment_prefix}}example: {{{name}}}{{comment_suffix}}\n{{{code}}}\n```\n'
208+
209+
# Logger
210+
log_level = logging.INFO
211+
212+
# Code block indicators
213+
start_flag = 'an example'
214+
end_flag = 'end of example'
215+
216+
# Hidden block indicators
217+
cloak_flag = 'cloak'
218+
uncloak_flag = 'uncloak'
219+
220+
# Validation and formatting logic
221+
drop_lines = [] # drop lines containing these phrases
222+
replacements = {'self.': ''} # straightforward replacements
223+
fail_on_contains = ['assert'] # fail if these strings are found in code blocks
224+
auto_dedent = True # keep code left-aligned with the start flag
225+
fail_on_dedent = True # fail if code is dedented before reaching the end flag
226+
stop_on_first_failure = False # fail early
227+
```

‎src/snippet/config.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ class Config:
1414
output_append = True # if the output file exists, append to it
1515
output_dir = '.'
1616
output_file_name_template = '{{name}}.md' # a mustache template for the output file name
17-
write_attempts = 3
17+
write_attempts = 3# number of retries when writing output files
1818

1919
# Language and style
2020
language_name = 'python'
@@ -23,7 +23,7 @@ class Config:
2323
# a mustache template for each file (triple braces important for code literals, no escaping)
2424
output_template = '```{{language_name}}\n{{comment_prefix}}example: {{{name}}}{{comment_suffix}}\n{{{code}}}\n```\n'
2525

26-
# logger
26+
# Logger
2727
log_level = logging.INFO
2828

2929
# Code block indicators
@@ -35,6 +35,7 @@ class Config:
3535
uncloak_flag = 'uncloak'
3636

3737
# Validation and formatting logic
38+
drop_lines = [] # drop lines containing these phrases
3839
replacements = {'self.': ''} # straightforward replacements
3940
fail_on_contains = ['assert'] # fail if these strings are found in code blocks
4041
auto_dedent = True # keep code left-aligned with the start flag

‎src/snippet/snippet.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@ def extract_snippets(config: Config, lines, path):
5353
if config.fail_on_dedent and any(line[:current_strip].lstrip()):
5454
raise exceptions.ValidationFailure(f'Unexpected dedent whilst capturing {current_debug_key}')
5555
clean_line = line[current_strip:].rstrip()
56+
if any(match in clean_line for match in config.drop_lines):
57+
continue
5658
for r_before, r_after in config.replacements.items():
5759
clean_line = clean_line.replace(r_before, r_after)
5860
for trigger in config.fail_on_contains:

‎tests/test_parser.py‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,3 +164,28 @@ def test_multiple(self):
164164
for i, parsed in enumerate(self.go(Config(), sequence)):
165165
with self.subTest(attempt=i):
166166
self.assertEqual(sample_output, parsed)
167+
168+
def test_drop_lines(self):
169+
config = Config()
170+
config.drop_lines = ['# ignore me']
171+
self.go_exact(
172+
config,
173+
[start, 'test', newline,
174+
A,
175+
'# ignore me, this comment is unhelpful\n',
176+
B, C,
177+
stop, 'other stuff']
178+
)
179+
180+
def test_replacements(self):
181+
config = Config()
182+
config.replacements = {'self.': ''}
183+
self.go_exact(
184+
config,
185+
[start, 'test', newline,
186+
'self.' + A,
187+
B,
188+
C,
189+
stop]
190+
)
191+

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /