Skip to content

Commit a1da6ef

Browse files
gertvdijkgertvdijk
committed
Move to Zensical for documentation
MkDocs 1.x is unmaintained and I saw three alternatives going forward here: 1. Move to Zensical; an MkDocs-like project with the material theme included. In fact, Zensical is built by the mkdocs-material team. The migration is not effortless, but I think PyKMP is the kind of project Zensical says it is targeting for minimal-change compatibility. Current limitations in the mkdocstrings support do not seem to apply for PyKMP. 2. Move to ProperDocs + MaterialX; drop-in replacement, but unsure about its future. Seems less popular at the time of writing. Minimizing the migration cost is not a key benefit for PyKMP given the low complexity of the documentation. 3. Wait for MkDocs 2.0: unsure when it is released and likely won't be including the features we need (Python API docs) with the plugin system removed. The first option looks like the most sensible pick and is carried out with this change. Implementation notes: - Opted in to migrate from mkdocs.yml-style configuration to a native zensical.toml file. Used OpenAI Codex to do the first heavy lifting of conversion for me. - Opted in for the 'modern' theme over the 'classic' theme; I think it looks slightly more appealing to the eye. - With Zensical lacking a `gh-deploy` subcommand to deploy to GitHub Pages, this adds instructions how to do this using `ghp-import` for now.
1 parent 173862d commit a1da6ef

5 files changed

Lines changed: 148 additions & 137 deletions

File tree

‎docs/contributing.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ the owners of this repository before making a change.
5959
1. Verify that you can build the documentation.
6060

6161
```console
62-
$ uv run mkdocs build
62+
$ uv run zensical build
6363
[...]
6464
INFO - Documentation built in 0.65 seconds
6565
```

‎docs/releasing.md‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ instead of the final release version.
2525
```console
2626
$ uv run ./run-all-linters
2727
$ uv run pytest
28-
$ uv run mkdocs build
28+
$ uv run zensical build
2929
```
3030

3131
1. Create the release tag on the release commit:
@@ -86,3 +86,24 @@ instead of the final release version.
8686
$ git push origin HEAD
8787
$ git push origin 0.0.2
8888
```
89+
90+
## Publish documentation
91+
92+
1. Build the documentation:
93+
94+
```console
95+
$ uv run zensical build --clean
96+
```
97+
98+
1. Publish using `ghp-import`:
99+
100+
```console
101+
$ COMMIT_ID="$(git describe --dirty)"
102+
$ ZENSICAL_VERSION="$(uv run zensical --version)"
103+
$ uv run ghp-import \
104+
--no-jekyll \
105+
--message="Deployed ${COMMIT_ID} with Zensical version ${ZENSICAL_VERSION}" \
106+
--remote=origin \
107+
--push \
108+
site/
109+
```

‎mkdocs.yml‎

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

‎pyproject.toml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,8 @@ dev = [
5050
"check-wheel-contents>=0.6.0",
5151
"click",
5252
"crc>=5.0.0", # typed since 5.0.0
53-
"mkdocs-material",
54-
"mkdocs<2", # 2.0 is a full rewrite, probably incompatible
55-
"mkdocstrings[python]>=0.23",
53+
"ghp-import",
54+
"mkdocstrings-python",
5655
"mock_serial",
5756
"mypy>=1.10.0",
5857
"pyright>=1.1.402",
@@ -67,6 +66,7 @@ dev = [
6766
# Backport Python 3.11 typing features to 3.10: 'assert_type', 'Self'.
6867
"typing_extensions; python_version < '3.11'",
6968
"validate-pyproject[all]",
69+
"zensical>=0.0.11",
7070
]
7171

7272
[project.urls]

‎zensical.toml‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# SPDX-FileCopyrightText: 2026 Gert van Dijk <github@gertvandijk.nl>
2+
#
3+
# SPDX-License-Identifier: CC0-1.0
4+
5+
[project]
6+
site_name = "PyKMP"
7+
site_url = "https://gertvdijk.github.io/PyKMP/"
8+
docs_dir = "docs"
9+
site_dir = "site"
10+
repo_url = "https://github.com/gertvdijk/PyKMP"
11+
repo_name = "gertvdijk/PyKMP"
12+
copyright = "Copyright &copy; 2026 Gert van Dijk"
13+
nav = [
14+
{"Home" = "index.md"},
15+
"changelog.md",
16+
"getting-started.md",
17+
"hardware-requirements.md",
18+
"battery-consumption.md",
19+
"ser2net.md",
20+
"troubleshooting.md",
21+
"thanks.md",
22+
{"Use cases" = [
23+
"store-graph-metrics.md",
24+
]},
25+
{"Development" = [
26+
{"API reference" = [
27+
"api/index.md",
28+
{"Client" = "api/client.md"},
29+
{"Messages" = "api/messages.md"},
30+
{"Codec" = "api/codec.md"},
31+
{"Constants" = "api/constants.md"},
32+
]},
33+
"contributing.md",
34+
"releasing.md",
35+
"resources.md",
36+
]},
37+
]
38+
39+
[project.theme]
40+
features = [
41+
"content.code.annotate",
42+
"navigation.expand",
43+
"navigation.footer",
44+
"navigation.sections",
45+
"navigation.tracking",
46+
]
47+
48+
[project.theme.icon]
49+
logo = "material/meter-electric"
50+
repo = "fontawesome/brands/github"
51+
52+
[[project.theme.palette]]
53+
media = "(prefers-color-scheme: light)"
54+
scheme = "default"
55+
primary = "teal"
56+
accent = "deep purple"
57+
toggle.icon = "material/weather-night"
58+
toggle.name = "Switch to dark mode"
59+
60+
[[project.theme.palette]]
61+
media = "(prefers-color-scheme: dark)"
62+
scheme = "slate"
63+
primary = "brown"
64+
accent = "deep orange"
65+
toggle.icon = "material/weather-sunny"
66+
toggle.name = "Switch to light mode"
67+
68+
[[project.extra.social]]
69+
icon = "fontawesome/brands/mastodon"
70+
link = "https://mastodon.social/@gertvdijk"
71+
name = "Gert van Dijk on Mastodon"
72+
73+
[[project.extra.social]]
74+
icon = "fontawesome/brands/bluesky"
75+
link = "https://bsky.app/profile/i6t.nl"
76+
name = "Gert van Dijk on Bluesky"
77+
78+
[[project.extra.social]]
79+
icon = "fontawesome/brands/github"
80+
link = "https://github.com/gertvdijk/"
81+
name = "Gert van Dijk on GitHub"
82+
83+
[[project.extra.social]]
84+
icon = "simple/pypi"
85+
link = "https://pypi.org/project/PyKMP/"
86+
name = "PyKMP on PyPI.org"
87+
88+
[project.markdown_extensions.abbr]
89+
[project.markdown_extensions.admonition]
90+
[project.markdown_extensions.attr_list]
91+
[project.markdown_extensions.footnotes]
92+
[project.markdown_extensions.pymdownx.critic]
93+
[project.markdown_extensions.pymdownx.caret]
94+
[project.markdown_extensions.pymdownx.details]
95+
[project.markdown_extensions.pymdownx.emoji]
96+
emoji_generator = "zensical.extensions.emoji.to_svg"
97+
emoji_index = "zensical.extensions.emoji.twemoji"
98+
[project.markdown_extensions.pymdownx.highlight]
99+
anchor_linenums = true
100+
[project.markdown_extensions.pymdownx.keys]
101+
[project.markdown_extensions.pymdownx.mark]
102+
[project.markdown_extensions.pymdownx.snippets]
103+
[project.markdown_extensions.pymdownx.superfences]
104+
[project.markdown_extensions.pymdownx.tasklist]
105+
custom_checkbox = true
106+
[project.markdown_extensions.pymdownx.tilde]
107+
[project.markdown_extensions.toc]
108+
toc_depth = 3
109+
110+
[project.plugins.mkdocstrings.handlers.python]
111+
paths = ["src"]
112+
113+
[project.plugins.mkdocstrings.handlers.python.options]
114+
group_by_category = true
115+
heading_level = 3
116+
inherited_members = true
117+
line_length = 88
118+
members_order = "source"
119+
show_if_no_docstring = true
120+
show_root_heading = true
121+
show_signature_annotations = true
122+
show_source = false

0 commit comments

Comments
 (0)