Skip to content

Commit fc1967f

Browse files
benoit74benoit74
authored
Merge pull request #215 from josephlewis42/jl/feat/mkdocs
Added mkdocs
2 parents 5a002d2 + cb91ca2 commit fc1967f

8 files changed

Lines changed: 213 additions & 37 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1616

1717
- Add `filesystem.validate_folder_writable` to check if a folder can be written to #200
1818
- Expose `constants.VERSION` to have access to zimscraperlib version from scrapers #224
19+
- Added mkdocs based documentation site. #92
1920

2021
### Fixed
2122

‎docs/assets/openzim.png‎

9.69 KB
Loading

‎docs/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: zimscraperlib Documentation
3+
---
4+
5+
{%
6+
include-markdown "../README.md"
7+
%}

‎docs/license.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: License
3+
---
4+
5+
```
6+
--8<-- "LICENSE"
7+
```

‎docs/scripts/generate_api_nav.py‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
"""
2+
Script called by mkdocs-gen-files that generates markdown documents
3+
with API reference placeholders.
4+
5+
https://oprypin.github.io/mkdocs-gen-files/api.html
6+
"""
7+
8+
from pathlib import Path
9+
10+
import mkdocs_gen_files
11+
12+
nav = mkdocs_gen_files.Nav()
13+
14+
root = Path(__file__).parent.parent.parent
15+
src = root / "src"
16+
api_reference = Path("api_reference")
17+
18+
for path in sorted(src.rglob("*.py")):
19+
module_path = path.relative_to(src).with_suffix("")
20+
21+
# Package docs get the parent module name.
22+
if module_path.name == "__init__":
23+
module_path = module_path.parent
24+
elif module_path.name.startswith("_"):
25+
# Skip other hidden items
26+
continue
27+
identifier = ".".join(module_path.parts)
28+
29+
doc_path = identifier + ".md"
30+
full_doc_path = api_reference / doc_path
31+
32+
nav[identifier] = doc_path
33+
34+
# Create a document with mkdocstrings placeholders.
35+
with mkdocs_gen_files.open(full_doc_path, "w") as fd:
36+
fd.write(f"---\ntitle: {identifier}\n---\n\n::: {identifier}")
37+
38+
# Make the edit button on the page link to the source file.
39+
mkdocs_gen_files.set_edit_path(full_doc_path, Path("..") / path.relative_to(root))
40+
41+
# Write a navigation file that will be interpreted by literate-nav.
42+
with mkdocs_gen_files.open(api_reference / "NAVIGATION.md", "w") as fd:
43+
fd.writelines(nav.build_literate_nav())

‎mkdocs.yml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
site_name: Python Scraperlib
2+
site_description: 'Collection of Python code to re-use across Python-based OpenZIM scrapers.'
3+
repo_url: https://github.com/openzim/python-scraperlib
4+
repo_name: GitHub
5+
edit_uri: edit/main/docs/
6+
7+
validation:
8+
omitted_files: warn
9+
absolute_links: warn
10+
unrecognized_links: warn
11+
12+
nav:
13+
- Home: index.md
14+
- Design:
15+
- Functional Architecture: functional_architecture.md
16+
- Software Architecture: software_architecture.md
17+
- Technical Architecture: technical_architecture.md
18+
- API Reference: api_reference/
19+
- License: license.md
20+
21+
theme:
22+
name: material
23+
logo: assets/openzim.png
24+
palette:
25+
# Light mode
26+
- scheme: default
27+
toggle:
28+
icon: material/brightness-7
29+
name: Switch to dark mode
30+
# Dark mode
31+
- scheme: slate
32+
toggle:
33+
icon: material/brightness-4
34+
name: Switch to light mode
35+
features:
36+
# Use XHR for page changes to avoid page flash during navigation.
37+
- navigation.instant
38+
- navigation.instant.progress
39+
# Use tabs and section headers rather than a single side navbar.
40+
- navigation.tabs
41+
- navigation.sections
42+
# Add buttons to edit content
43+
- content.action.edit
44+
45+
markdown_extensions:
46+
- pymdownx.snippets:
47+
base_path: .
48+
check_paths: true
49+
50+
plugins:
51+
- search
52+
53+
# Replace externally hosted assets for compliance with various privacy regulations.
54+
- privacy
55+
56+
# Nicely include markdown, e.g. to rewrite relative links
57+
- include-markdown
58+
59+
# Generate API docs and navigation for them
60+
- gen-files:
61+
scripts:
62+
- docs/scripts/generate_api_nav.py
63+
64+
# Import additional nav from NAVIGATION.md files, like the one produced
65+
# by gen-files.
66+
- literate-nav:
67+
nav_file: NAVIGATION.md
68+
69+
# Generate items
70+
- mkdocstrings:
71+
handlers:
72+
python:
73+
# Set up cross-references to Python types
74+
import:
75+
- https://docs.python.org/3/objects.inv
76+
paths: [src]
77+
options:
78+
docstring_section_style: list
79+
filters: ['!^_']
80+
heading_level: 2
81+
inherited_members: true
82+
merge_init_into_class: true
83+
separate_signature: true
84+
show_signature_annotations: true
85+
show_symbol_type_heading: true
86+
show_symbol_type_toc: true
87+
signature_crossrefs: true
88+
summary: true
89+
# Typically this should be off, but zimscraperlib has many
90+
# items that won't be picked up because they lack docs
91+
# or are using single line comments (like constants).
92+
show_if_no_docstring: true

‎pyproject.toml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,24 @@ features = ["scripts", "check"]
131131
pyright = "inv check-pyright --args '{args}'"
132132
all = "inv checkall --args '{args}'"
133133

134+
[tool.hatch.envs.docs]
135+
template = "docs"
136+
detached = true
137+
dependencies = [
138+
"mkdocs==1.6.1",
139+
"mkdocstrings[python]==0.27.0",
140+
"mkdocs-material==9.5.44",
141+
"pymdown-extensions==10.12",
142+
"mkdocs-gen-files==0.5.0",
143+
"mkdocs-literate-nav==0.6.1",
144+
"mkdocs-include-markdown-plugin==7.1.2",
145+
"black==24.10.0",
146+
]
147+
148+
[tool.hatch.envs.docs.scripts]
149+
serve = "mkdocs serve"
150+
build = "mkdocs build"
151+
134152
[tool.black]
135153
line-length = 88
136154
target-version = ['py312']

‎src/zimscraperlib/image/optimization.py‎

Lines changed: 45 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -68,15 +68,15 @@ def optimize_png(
6868
Arguments:
6969
reduce_colors: Whether to reduce colors using adaptive color pallette (boolean)
7070
values: True | False
71-
max_colors: Maximum number of colors
72-
if reduce_colors is True (integer between 1 and 256)
71+
max_colors: Maximum number of colors if reduce_colors is True (integer between
72+
1 and 256)
7373
values: 35 | 64 | 256 | 128 | XX
7474
fast_mode: Whether to use faster but weaker compression (boolean)
7575
values: True | False
7676
remove_transparency: Whether to remove transparency (boolean)
7777
values: True | False
78-
background_color: Background color
79-
if remove_transparency is True (tuple containing RGB values)
78+
background_color: Background color if remove_transparency is True (tuple
79+
containing RGB values)
8080
values: (255, 255, 255) | (221, 121, 108) | (XX, YY, ZZ)"""
8181

8282
ensure_matches(src, "PNG")
@@ -110,13 +110,15 @@ def optimize_jpeg(
110110
**_,
111111
) -> pathlib.Path | io.BytesIO:
112112
"""method to optimize JPEG files using a pure python external optimizer
113-
quality: JPEG quality (integer between 1 and 100)
114-
values: 50 | 55 | 35 | 100 | XX
115-
keep_exif: Whether to keep EXIF data in JPEG (boolean)
116-
values: True | False
117-
fast_mode: Use the supplied quality value. If turned off, optimizer will
118-
get dynamic quality value to ensure better compression
119-
values: True | False"""
113+
114+
Arguments:
115+
quality: JPEG quality (integer between 1 and 100)
116+
values: 50 | 55 | 35 | 100 | XX
117+
keep_exif: Whether to keep EXIF data in JPEG (boolean)
118+
values: True | False
119+
fast_mode: Use the supplied quality value. If turned off, optimizer will
120+
get dynamic quality value to ensure better compression
121+
values: True | False"""
120122

121123
ensure_matches(src, "JPEG")
122124

@@ -179,14 +181,16 @@ def optimize_webp(
179181
**_,
180182
) -> pathlib.Path | io.BytesIO:
181183
"""method to optimize WebP using Pillow options
182-
lossless: Whether to use lossless compression (boolean)
183-
values: True | False
184-
quality: WebP quality for lossy, effort put into compression
185-
for lossless (integer between 0 to 100)
186-
values: 30 | 45 | 100 | XX
187-
method: Quality/speed trade-off;
188-
higher values give better compression (integer between 1 and 6)
189-
values: 1 | 2 | 3 | 4 | 5 | 6
184+
185+
Arguments:
186+
lossless: Whether to use lossless compression (boolean);
187+
values: True | False
188+
quality: WebP quality for lossy, effort put into compression for lossless
189+
(integer between 0 to 100);
190+
values: 30 | 45 | 100 | XX
191+
method: Quality/speed trade-off; higher values give better compression (integer
192+
between 1 and 6);
193+
values: 1 | 2 | 3 | 4 | 5 | 6
190194
191195
refer to the link for more details
192196
https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#webp"""
@@ -230,18 +234,21 @@ def optimize_gif(
230234
**_,
231235
) -> pathlib.Path:
232236
"""method to optimize GIFs using gifsicle >= 1.92
233-
optimize_level: Optimization level;
234-
higher values give better compression (integer between 1 and 3)
235-
values: 1 | 2 | 3
236-
lossiness: Level of lossy optimization to use;
237-
higher values give better compression (integer)
238-
values: 20 | 45 | 80 | XX
239-
interlace: Whether to interlace the frames (boolean)
240-
values: True | False
241-
no_extensions: Whether to remove all extension options from GIF (boolean)
242-
values: True | False
243-
max_colors: Maximum number of colors in resultant GIF (integer between 2 and 256)
244-
values: 2 | 86 | 128 | 256 | XX
237+
238+
Arguments:
239+
optimize_level: Optimization level; higher values give better compression
240+
(integer between 1 and 3);
241+
values: 1 | 2 | 3
242+
lossiness: Level of lossy optimization to use; higher values give better
243+
compression (integer)
244+
values: 20 | 45 | 80 | XX
245+
interlace: Whether to interlace the frames (boolean)
246+
values: True | False
247+
no_extensions: Whether to remove all extension options from GIF (boolean)
248+
values: True | False
249+
max_colors: Maximum number of colors in resultant GIF;
250+
(integer between 2 and 256)
251+
values: 2 | 86 | 128 | 256 | XX
245252
246253
refer to the link for more details - https://www.lcdf.org/gifsicle/man.html"""
247254

@@ -282,12 +289,13 @@ def optimize_image(
282289
):
283290
"""Optimize image, automatically selecting correct optimizer
284291
285-
delete_src: whether to remove src file upon success (boolean)
286-
values: True | False
287-
convert: whether/how to convert from source before optimizing (str or boolean)
288-
values: False: don't convert
289-
True: convert to format implied by dst suffix
290-
"FMT": convert to format FMT (use Pillow names)"""
292+
Arguments:
293+
delete_src: whether to remove src file upon success (boolean)
294+
values: True | False
295+
convert: whether/how to convert from source before optimizing (str or boolean)
296+
values: False: don't convert
297+
True: convert to format implied by dst suffix
298+
"FMT": convert to format FMT (use Pillow names)"""
291299

292300
src_format, dst_format = format_for(src, from_suffix=False), format_for(dst)
293301

0 commit comments

Comments
 (0)