-
-
Notifications
You must be signed in to change notification settings - Fork 42
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add possibilities to skip blocks and lines? #193
Comments
I'm using the pymdownx.snippets Markdown extension to include some Python code into a Python code block: ```python
--8<-- "docs/snippets/script.py
``` ...and blacken-docs reformats it to: ```python
--8 < -- "docs/snippets/script.py
``` ...breaking the extension's syntax. As a workaround, I'm using Markdown Exec (very hacky): ```python exec="1" result="python"
print('--8<-- "docs/examples/model_ext.py"')
``` This code blocks gets executed, so prints the actual snippet line, and this line then gets re-rendered as Markdown, wrapping the result into a Instead, it would be nice if I could somehow tell blacken-docs to ignore this code block, preferably without comments inside the code. |
Adding skip syntax would be great. It needs to be added for all supported markup languages. I think the easiest is to support on/off comments, and then we can ignore any detected examples that overlap the disabled regions. For example, in Markdown: <!-- blacken-docs:off -->
```python
--8<-- "docs/snippets/script.py
```
<!-- blacken-docs:on --> This would be quite a large undertaking, so I'm personally not going to invest in it right now. But I would love to see a PR. |
What do you think of this:
Quick example: comments = find_all_comments()
off_ranges = []
off_start = None
for comment in comments:
if "off" in comment and off_start is None:
off_start = comment.start()
elif "on" in comment and off_start is not None:
off_ranges.append((off_start, comment.end()))
off_start = None
def _off_range(start, end):
for range in off_ranges: # closure
if start >= range[0] and end <= range[1]:
return True
return False
# could rewrite as `return any(comprehension)`
# could use a partial instead of a closure
def _md_match(match):
if _off_range(match.start(), match.end()):
return match.group(0)
... # otherwise process normally |
Background:
When we implemented blacken-docs in Read the Docs, we had a couple of cases where we would have liked to skip linting of the code example. But we also didn't want to put
# noqa
in the code-examples themselves, since that means copy-pasting the code would also require additional clean-up. Our cases were - however - easy to ignore and move on from. So we did.Now, I see a Django proposal to use blacken-docs is generating mostly great changes, but there are also a few issues getting the PR merged.
Solution?
I'm not sure what would be a good way forwards. But I get the idea that being able to specify what to skip might work well.
Please have a look here: django/django#16261
Thanks for the great project ❤️
The text was updated successfully, but these errors were encountered: