docs!: build and version the online documentation with Zensical

Author: nandgator

.gitignore

@@ -139,7 +139,7 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# zensical documentation
 site/
 
 # mypy

CONTRIBUTING.md

@@ -51,8 +51,8 @@ $ uv run python package/export TYPE # where TYPE is any of `doc`, `man` or `web`
 You can preview the generated documentation:
 
 ```sh
-# To preview mkdocs
-$ uv run mkdocs serve
+# To preview the online documentation
+$ uv run --group docs-online zensical serve
 # To preview man pages
 $ man docs/_build/man/validators.1
 # To preview sphinx webpages

MANIFEST.in

@@ -3,7 +3,7 @@
 
 # include
 include CHANGES.md
-include mkdocs.yaml
+include mkdocs.yml
 
 
 # global-include

mkdocs.yaml mkdocs.ymlmkdocs.yaml renamed to mkdocs.yml

@@ -50,8 +50,6 @@ plugins:
             show_root_heading: true
           inventories:
             - https://docs.python-requests.org/en/master/objects.inv
-  - git-revision-date-localized
-  - mike
 
 extra:
   social:

package/export/__main__.py

@@ -48,10 +48,10 @@ def _gen_md_docs(source: Path, refs_path: Path):
     for module_name, aliases in _parse_package(source / "src/validators/__init__.py"):
         for alias in aliases:
             _write_ref_content(refs_path / f"{module_name}.md", module_name, alias.name)
-    # build mkdocs as subprocess
-    mkdocs_build = Popen(("mkdocs", "build"))  # nosec
-    mkdocs_build.communicate()
-    return mkdocs_build.returncode
+    # build zensical as subprocess
+    zensical_build = Popen(("zensical", "build"))  # nosec
+    zensical_build.communicate()
+    return zensical_build.returncode
 
 
 def _hide_badges_from_man(rst: str):

pyproject.toml

@@ -61,12 +61,9 @@ docs-offline = [
     "furo>=2024.8.6",
 ]
 docs-online = [
-    "mkdocs>=1.6.1",
-    "mkdocs-git-revision-date-localized-plugin>=1.2.7",
-    "mkdocs-material>=9.5.34",
-    "mkdocstrings[python]>=0.26.0",
+    "zensical>=0.0.69",
     "mkdocstrings-python>=1.14.0", # `inventories` option replaces `import`
-    "mike>=2.1.3",
+    "mike", # Zensical-compatible fork, see `tool.uv.sources`
 ]
 package = ["build>=1.2.1"]
 runner = ["tox>=4.22"]
@@ -83,6 +80,10 @@ tooling = [
 #  Configurations  #
 ####################
 
+[tool.uv.sources]
+# Temporary: Zensical has no native versioning yet; this fork of `mike` bridges it.
+mike = { git = "https://github.com/squidfunk/mike.git" }
+
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["validators*"]