Skip to content

Commit 10097bc

Browse files
llucaxllucax
authored
Add the first implementation of line filtering (#3)
This is a custom superfence for pymdown-extensions that can filter lines by specifying a set of line ranges to show. The ranges are specified in the `show_lines` option, which is a comma-separated list of ranges, where each range is in the format `start:end` or `line`, where `start`, `end` and `line` are positive integers. If `start` is empty, it is assumed to be 1. If `end` is empty, it is assumed to be the end of the file. If only `line` is used, it is assumed to be both `start` and `end` (so allowing just one line). Lines are 1-indexed. Warnings are emitted if the `show_lines` option is invalid. There is a hacky way to determine if we are running inside MkDocs or not, and if we are then we use the MkDocs logger, so warnings are shown in the MkDocs output with special formatting and also are detected as such when running in *strict* mode. If we are not running inside MkDocs, then we use the logger for this module.
2 parents 6a14c35 + 2bb82b4 commit 10097bc

File tree

15 files changed

+952
-78
lines changed

15 files changed

+952
-78
lines changed

‎.cookiecutter-replay.json‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,17 @@
22
"cookiecutter": {
33
"Introduction": "",
44
"type": "lib",
5-
"name": "pymdown-superfence-filter-lines",
5+
"name": "pymdownx-superfences-filter-lines",
66
"description": "A custom superfence for pymdown-extensions that can filters lines and plays nice with MkDocs",
77
"title": "Frequenz Filter Lines Superfence",
8-
"keywords": "markdown, filter, mkdocs, python3, mkdocs-material, pymdown, pymdown-extensions, superfence",
8+
"keywords": "markdown, filter, mkdocs, python3, mkdocs-material, pymdownx, pymdown-extensions, superfence",
99
"github_org": "frequenz-floss",
1010
"license": "MIT",
1111
"author_name": "Frequenz Energy-as-a-Service GmbH",
1212
"author_email": "[email protected]",
13-
"python_package": "frequenz.pymdown.superfence.filter_lines",
14-
"pypi_package_name": "frequenz-pymdown-superfence-filter-lines",
15-
"github_repo_name": "frequenz-pymdown-superfence-filter-lines-python",
13+
"python_package": "frequenz.pymdownx.superfences.filter_lines",
14+
"pypi_package_name": "frequenz-pymdownx-superfences-filter-lines",
15+
"github_repo_name": "frequenz-pymdownx-superfences-filter-lines-python",
1616
"default_codeowners": "(like @some-org/some-team; defaults to a team based on the repo type)",
1717
"_template": "gh:frequenz-floss/frequenz-repo-config-python",
1818
"_repo_dir": "/home/luca/.cookiecutters/frequenz-repo-config-python/cookiecutter",

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,5 @@
44
blank_issues_enabled: true
55
contact_links:
66
- name: Ask a question ❓
7-
url: https://github.com/frequenz-floss/frequenz-pymdown-superfence-filter-lines-python/discussions/new?category=support
7+
url: https://github.com/frequenz-floss/frequenz-pymdownx-superfences-filter-lines-python/discussions/new?category=support
88
about: Use this if you are not sure how to do something, have installation problems, etc.

‎.github/labeler.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@
99
# For example:
1010
#
1111
# "part:module":
12-
# - "src/frequenz/lib/pymdown_superfence_filter_lines/module/**"
12+
# - "src/frequenz/pymdownx/superfences/filter_lines/module/**"
1313
#
1414
# "part:other":
15-
# - "src/frequenz/lib/pymdown_superfence_filter_lines/other/**"
15+
# - "src/frequenz/pymdownx/superfences/filter_lines/other/**"
1616
#
1717
# # For excluding some files (in this example, label "part:complicated"
1818
# # everything inside src/ with a .py suffix, except for src/__init__.py)

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -139,9 +139,9 @@ These are the steps to create a new release:
139139

140140
5. A GitHub action will test the tag and if all goes well it will create
141141
a [GitHub
142-
Release](https://github.com/frequenz-floss/frequenz-pymdown-superfence-filter-lines-python/releases),
142+
Release](https://github.com/frequenz-floss/frequenz-pymdownx-superfences-filter-lines-python/releases),
143143
and upload a new package to
144-
[PyPI](https://pypi.org/project/frequenz-pymdown-superfence-filter-lines/)
144+
[PyPI](https://pypi.org/project/frequenz-pymdownx-superfences-filter-lines/)
145145
automatically.
146146

147147
6. Once this is done, reset the `RELEASE_NOTES.md` with the template:

‎README.md‎

Lines changed: 141 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,152 @@
11
# Frequenz Filter Lines Superfence
22

3-
[![Build Status](https://github.com/frequenz-floss/frequenz-pymdown-superfence-filter-lines-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-pymdown-superfence-filter-lines-python/actions/workflows/ci.yaml)
4-
[![PyPI Package](https://img.shields.io/pypi/v/frequenz-pymdown-superfence-filter-lines)](https://pypi.org/project/frequenz-pymdown-superfence-filter-lines/)
5-
[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-pymdown-superfence-filter-lines-python/)
3+
[![Build Status](https://github.com/frequenz-floss/frequenz-pymdownx-superfences-filter-lines-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-pymdownx-superfences-filter-lines-python/actions/workflows/ci.yaml)
4+
[![PyPI Package](https://img.shields.io/pypi/v/frequenz-pymdownx-superfences-filter-lines)](https://pypi.org/project/frequenz-pymdownx-superfences-filter-lines/)
5+
[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-pymdownx-superfences-filter-lines-python/)
66

77
## Introduction
88

9-
A custom superfence for pymdown-extensions that can filters lines and plays nice with MkDocs.
9+
A custom superfence for pymdown-extensions that can filters lines and plays
10+
nice with MkDocs.
1011

11-
## Supported Platforms
12+
This is particularly useful when you want to hide some comments or some
13+
boilerplate code from the documentation for any reason.
1214

13-
The following platforms are officially supported (tested):
15+
A typical use case is when you are testing your examples in the documentation,
16+
so you might need to add some initialization code, or importing some dependencies
17+
that are not relevant for the point you are trying to make in the
18+
documentation, but you still need the example code to work to make sure they are
19+
not inadvertedly broken.
1420

15-
- **Python:** 3.11
16-
- **Operating System:** Ubuntu Linux 20.04
17-
- **Architectures:** amd64, arm64
21+
## Quick Example
22+
23+
When writing some documentation, and you want to show some code block, but
24+
you want to show only some lines, you can use this superfence as follows:
25+
26+
~~~markdown
27+
```text show_lines=":2,4,7,10:12,15:"
28+
This is line 1
29+
This is line 2
30+
This is line 3
31+
This is line 4
32+
This is line 5
33+
This is line 6
34+
This is line 7
35+
This is line 8
36+
This is line 9
37+
This is line 10
38+
This is line 11
39+
This is line 12
40+
This is line 13
41+
This is line 14
42+
This is line 15
43+
This is line 16
44+
This is line 17
45+
```
46+
~~~
47+
48+
This will show the following block of code in the rendered output:
49+
50+
```text show_lines=":2,4,7,10:12,15:"
51+
This is line 1
52+
This is line 2
53+
This is line 3
54+
This is line 4
55+
This is line 5
56+
This is line 6
57+
This is line 7
58+
This is line 8
59+
This is line 9
60+
This is line 10
61+
This is line 11
62+
This is line 12
63+
This is line 13
64+
This is line 14
65+
This is line 15
66+
This is line 16
67+
This is line 17
68+
```
69+
70+
See [Usage](#usage) for a more detailed explanation of the available options.
71+
72+
## Configuration
73+
74+
### MkDocs
75+
76+
To use this superfence with [MkDocs](https://www.mkdocs.org/), you can use
77+
something like this:
78+
79+
```yaml
80+
markdown_extensions:
81+
- pymdownx.superfences:
82+
custom_fences:
83+
- name: "*"
84+
class: "highlight"
85+
format: !!python/name:frequenz.pymdownx.superfences.filter_lines.do_format
86+
validator: !!python/name:frequenz.pymdownx.superfences.filter_lines.do_validate
87+
```
88+
89+
### Standalone
90+
91+
To use this superfence standalone, you can use something like this:
92+
93+
```python
94+
import markdown
95+
from frequenz.pymdownx.superfences.filter_lines import do_format, do_validate
96+
97+
html = markdown.markdown(
98+
markdown_source,
99+
extensions=['pymdownx.superfences'],
100+
extension_configs={
101+
"pymdownx.superfences": {
102+
"custom_fences": [
103+
{
104+
'name': '*',
105+
'class': 'highlight',
106+
'validator': do_validate,
107+
'format': do_format
108+
}
109+
]
110+
}
111+
}
112+
)
113+
114+
print(html)
115+
```
116+
117+
## Usage
118+
119+
See [Quick Example](#quick-example) for an example.
120+
121+
The superfence supports the following options:
122+
123+
### `show_lines`
124+
125+
A comma separated list of line numbers or ranges of line numbers to show.
126+
127+
The line numbers are 1-based. If any line number is zero or negative, a warning
128+
is logged and the line or range are ignored.
129+
130+
If `show_lines` is omitted, it defaults to showing all lines.
131+
132+
#### Ranges
133+
134+
Ranges are inclusive and are defined as follows:
135+
136+
* The ranges are specified as `start:end`, where `start` and `end` are the line
137+
numbers of the first and last lines to show, respectively.
138+
139+
* If `start` is omitted, it defaults to the first line. If `end` is omitted, it
140+
defaults to the last line.
141+
142+
* If `start` is greater than `end`, a warning is logged and the range is
143+
ignored.
144+
145+
* If `start` is greater than the number of lines in the code block, the range
146+
is ignored.
147+
148+
* If `end` is greater than the number of lines in the code block, it is set to
149+
the number of lines in the code block.
18150

19151
## Contributing
20152

‎mkdocs.yml‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ site_name: "Frequenz Filter Lines Superfence"
66
site_description: "A custom superfence for pymdown-extensions that can filters lines and plays nice with MkDocs"
77
site_author: "Frequenz Energy-as-a-Service GmbH"
88
copyright: "Copyright © 2023 Frequenz Energy-as-a-Service GmbH"
9-
repo_name: "frequenz-pymdown-superfence-filter-lines-python"
10-
repo_url: "https://github.com/frequenz-floss/frequenz-pymdown-superfence-filter-lines-python"
9+
repo_name: "frequenz-pymdownx-superfences-filter-lines-python"
10+
repo_url: "https://github.com/frequenz-floss/frequenz-pymdownx-superfences-filter-lines-python"
1111
edit_uri: "edit/v0.x.x/docs/"
1212
strict: true # Treat warnings as errors
1313

@@ -80,6 +80,10 @@ markdown_extensions:
8080
- name: mermaid
8181
class: mermaid
8282
format: !!python/name:pymdownx.superfences.fence_code_format
83+
- name: "*"
84+
class: "highlight"
85+
format: !!python/name:frequenz.pymdownx.superfences.filter_lines.do_format
86+
validator: !!python/name:frequenz.pymdownx.superfences.filter_lines.do_validate
8387
- pymdownx.tabbed
8488
- pymdownx.tasklist:
8589
custom_checkbox: true

‎pyproject.toml‎

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ requires = [
1010
build-backend = "setuptools.build_meta"
1111

1212
[project]
13-
name = "frequenz-pymdown-superfence-filter-lines"
13+
name = "frequenz-pymdownx-superfences-filter-lines"
1414
description = "A custom superfence for pymdown-extensions that can filters lines and plays nice with MkDocs"
1515
readme = "README.md"
1616
license = { text = "MIT" }
@@ -19,13 +19,13 @@ keywords = [
1919
"python",
2020
"lib",
2121
"library",
22-
"pymdown-superfence-filter-lines",
22+
"pymdownx-superfences-filter-lines",
2323
"markdown",
2424
"filter",
2525
"mkdocs",
2626
"python3",
2727
"mkdocs-material",
28-
"pymdown",
28+
"pymdownx",
2929
"pymdown-extensions",
3030
"superfence",
3131
]
@@ -39,6 +39,7 @@ classifiers = [
3939
"Typing :: Typed",
4040
]
4141
requires-python = ">= 3.11, < 4"
42+
dependencies = ["Markdown >= 3.5, < 4", "pymdown-extensions >= 10, < 11"]
4243
dynamic = ["version"]
4344

4445
[[project.authors]]
@@ -56,7 +57,7 @@ dev-flake8 = [
5657
dev-formatting = ["black == 23.9.1", "isort == 5.12.0"]
5758
dev-mkdocs = [
5859
"black == 23.9.1",
59-
"Markdown==3.4.4",
60+
"Markdown==3.5",
6061
"mike == 2.0.0",
6162
"mkdocs-gen-files == 0.5.0",
6263
"mkdocs-literate-nav == 0.6.1",
@@ -69,13 +70,13 @@ dev-mypy = [
6970
"mypy == 1.5.1",
7071
"types-Markdown == 3.4.2.10",
7172
# For checking the noxfile, docs/ script, and tests
72-
"frequenz-pymdown-superfence-filter-lines[dev-mkdocs,dev-noxfile,dev-pytest]",
73+
"frequenz-pymdownx-superfences-filter-lines[dev-mkdocs,dev-noxfile,dev-pytest]",
7374
]
7475
dev-noxfile = ["nox == 2023.4.22", "frequenz-repo-config[lib] == 0.7.5"]
7576
dev-pylint = [
7677
"pylint == 3.0.2",
7778
# For checking the noxfile, docs/ script, and tests
78-
"frequenz-pymdown-superfence-filter-lines[dev-mkdocs,dev-noxfile,dev-pytest]",
79+
"frequenz-pymdownx-superfences-filter-lines[dev-mkdocs,dev-noxfile,dev-pytest]",
7980
]
8081
dev-pytest = [
8182
"pytest == 7.4.2",
@@ -85,15 +86,15 @@ dev-pytest = [
8586
"async-solipsism == 0.5",
8687
]
8788
dev = [
88-
"frequenz-pymdown-superfence-filter-lines[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
89+
"frequenz-pymdownx-superfences-filter-lines[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
8990
]
9091

9192
[project.urls]
92-
Documentation = "https://frequenz-floss.github.io/frequenz-pymdown-superfence-filter-lines-python/"
93-
Changelog = "https://github.com/frequenz-floss/frequenz-pymdown-superfence-filter-lines-python/releases"
94-
Issues = "https://github.com/frequenz-floss/frequenz-pymdown-superfence-filter-lines-python/issues"
95-
Repository = "https://github.com/frequenz-floss/frequenz-pymdown-superfence-filter-lines-python"
96-
Support = "https://github.com/frequenz-floss/frequenz-pymdown-superfence-filter-lines-python/discussions/categories/support"
93+
Documentation = "https://frequenz-floss.github.io/frequenz-pymdownx-superfences-filter-lines-python/"
94+
Changelog = "https://github.com/frequenz-floss/frequenz-pymdownx-superfences-filter-lines-python/releases"
95+
Issues = "https://github.com/frequenz-floss/frequenz-pymdownx-superfences-filter-lines-python/issues"
96+
Repository = "https://github.com/frequenz-floss/frequenz-pymdownx-superfences-filter-lines-python"
97+
Support = "https://github.com/frequenz-floss/frequenz-pymdownx-superfences-filter-lines-python/discussions/categories/support"
9798

9899
[tool.black]
99100
line-length = 88
@@ -157,11 +158,11 @@ namespace_packages = true
157158
# used but getting the original ignored error when removing the type: ignore.
158159
# See for example: https://github.com/python/mypy/issues/2960
159160
#no_incremental = true
160-
packages = ["frequenz.pymdown.superfence.filter_lines"]
161+
packages = ["frequenz.pymdownx.superfences.filter_lines"]
161162
strict = true
162163

163164
[[tool.mypy.overrides]]
164-
module = ["mkdocs_macros.*", "sybil", "sybil.*"]
165+
module = ["mkdocs_macros.*", "pymdownx.*", "sybil", "sybil.*"]
165166
ignore_missing_imports = true
166167

167168
[tool.setuptools_scm]

‎src/frequenz/pymdown_superfence_filter_lines/__init__.py‎

Lines changed: 0 additions & 25 deletions
This file was deleted.

0 commit comments

Comments
 (0)