Build docs with zensical instead of mkdocs (#172)

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: samuelcolvin

HISTORY.md

@@ -1,4 +1,4 @@
-.DEFAULT_GOAL := all
+.DEFAULT_GOAL := help
 
 .PHONY: .uv
 .uv:
@@ -50,12 +50,14 @@ clean: ## Clean up build artifacts
 
 .PHONY: docs
 docs: ## Build docs
-	uv run ruff check --line-length=80 docs/examples/
-	uv run mkdocs build
+	uv run ruff check --isolated --line-length=80 docs/examples/
+	uv run python docs/build.py
+	uv run zensical build --strict
 
 .PHONY: docs-serve
 docs-serve: ## Serve docs locally
-	uv run mkdocs serve
+	uv run python docs/build.py
+	uv run zensical serve
 
 # (must stay last!)
 .PHONY: help

Makefile

@@ -1,7 +1,7 @@
 # python devtools
 
 [![CI](https://github.com/samuelcolvin/python-devtools/workflows/CI/badge.svg?event=push)](https://github.com/samuelcolvin/python-devtools/actions?query=event%3Apush+branch%3Amain+workflow%3ACI)
-[![Coverage](https://codecov.io/gh/samuelcolvin/python-devtools/branch/main/graph/badge.svg)](https://codecov.io/gh/samuelcolvin/python-devtools)
+[![Coverage](https://coverage-badge.samuelcolvin.workers.dev/samuelcolvin/python-devtools.svg)](https://coverage-badge.samuelcolvin.workers.dev/redirect/samuelcolvin/python-devtools)
 [![pypi](https://img.shields.io/pypi/v/devtools.svg)](https://pypi.python.org/pypi/devtools)
 [![versions](https://img.shields.io/pypi/pyversions/devtools.svg)](https://github.com/samuelcolvin/python-devtools)
 [![license](https://img.shields.io/github/license/samuelcolvin/python-devtools.svg)](https://github.com/samuelcolvin/python-devtools/blob/main/LICENSE)
@@ -18,7 +18,7 @@ Just
 pip install devtools
 ```
 
-If you've got python 3.7+ and `pip` installed, you're good to go.
+If you've got python 3.10+ and `pip` installed, you're good to go.
 
 ## Usage
 

README.md

@@ -0,0 +1,51 @@
+"""
+Generate the files the docs include via `pymdownx.snippets` before zensical builds the site.
+
+Zensical has no plugin hooks, so anything that needs Python (running the examples to capture their coloured output,
+reading the package version) happens here, writing files which the markdown then includes.
+"""
+
+import logging
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from ansi2html import Ansi2HTMLConverter
+
+THIS_DIR = Path(__file__).parent
+PROJECT_ROOT = THIS_DIR.parent
+
+logger = logging.getLogger('docs.build')
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format='%(message)s')
+    build_version()
+    build_examples()
+
+
+def build_version() -> None:
+    from devtools import __version__
+
+    write_if_changed(THIS_DIR / '.version.md', f'Documentation for version: **v{__version__}**\n')
+
+
+def build_examples() -> None:
+    env = {**os.environ, 'PY_DEVTOOLS_HIGHLIGHT': 'true', 'PY_DEVTOOLS_WIDTH': '80'}
+    conv = Ansi2HTMLConverter()
+    for example in sorted((THIS_DIR / 'examples').glob('*.py')):
+        logger.info('running %s to generate HTML...', example.relative_to(PROJECT_ROOT))
+        p = subprocess.run((sys.executable, str(example)), stdout=subprocess.PIPE, check=True, env=env, cwd=THIS_DIR)
+        html = conv.convert(p.stdout.decode(), full=False).strip('\r\n')
+        write_if_changed(example.with_suffix('.html'), f'<pre class="ansi2html-content">\n{html}\n</pre>\n')
+
+
+def write_if_changed(path: Path, content: str) -> None:
+    """Avoid touching files that haven't changed so `zensical serve` doesn't rebuild needlessly."""
+    if not path.exists() or path.read_text() != content:
+        path.write_text(content)
+
+
+if __name__ == '__main__':
+    main()

docs/build.py

@@ -1,19 +1,19 @@
 # Python devtools
 
 [![CI](https://github.com/samuelcolvin/python-devtools/workflows/CI/badge.svg?event=push)](https://github.com/samuelcolvin/python-devtools/actions?query=event%3Apush+branch%3Amain+workflow%3ACI)
-[![Coverage](https://codecov.io/gh/samuelcolvin/python-devtools/branch/main/graph/badge.svg)](https://codecov.io/gh/samuelcolvin/python-devtools)
+[![Coverage](https://coverage-badge.samuelcolvin.workers.dev/samuelcolvin/python-devtools.svg)](https://coverage-badge.samuelcolvin.workers.dev/redirect/samuelcolvin/python-devtools)
 [![pypi](https://img.shields.io/pypi/v/devtools.svg)](https://pypi.python.org/pypi/devtools)
 [![versions](https://img.shields.io/pypi/pyversions/devtools.svg)](https://github.com/samuelcolvin/python-devtools)
 [![license](https://img.shields.io/github/license/samuelcolvin/python-devtools.svg)](https://github.com/samuelcolvin/python-devtools/blob/main/LICENSE)
 
-{{ version }}
+--8<-- ".version.md"
 
 **Python's missing debug print command and other development tools.**
 
 ```py
-{!examples/example.py!}
+--8<-- "examples/example.py"
 ```
 
-{{ example_html(examples/example.py) }}
+--8<-- "examples/example.html"
 
 Python devtools can do much more, see [Usage](./usage.md) for examples.

docs/history.md

@@ -5,4 +5,4 @@ pip install devtools
 ```
 
 `devtools` has [very few dependencies](https://github.com/samuelcolvin/python-devtools/blob/main/pyproject.toml#L37).
-If you've got python 3.7+ and `pip` installed, you're good to go.
+If you've got python 3.10+ and `pip` installed, you're good to go.

docs/index.md

@@ -6,10 +6,10 @@ and readable way to print stuff during development. (If you know why this is, I'
 **The wait is over:**
 
 ```py
-{!examples/example.py!}
+--8<-- "examples/example.py"
 ```
 
-{{ example_html(examples/example.py) }}
+--8<-- "examples/example.html"
 
 `debug` is like `print` after a good night's sleep and lots of coffee:
 
@@ -21,10 +21,10 @@ and readable way to print stuff during development. (If you know why this is, I'
 A more complex example of `debug` shows more of what it can do.
 
 ```py
-{!examples/complex.py!}
+--8<-- "examples/complex.py"
 ```
 
-{{ example_html(examples/complex.py) }}
+--8<-- "examples/complex.html"
 
 ### Returning the arguments
 
@@ -37,10 +37,10 @@ The returned arguments work as follows:
 * if keyword arguments are passed to `debug()`, the `kwargs` dictionary is added to the returned tuple
 
 ```py
-{!examples/return_args.py!}
+--8<-- "examples/return_args.py"
 ```
 
-{{ example_html(examples/return_args.py) }}
+--8<-- "examples/return_args.html"
 
 ## Other debug tools
 
@@ -51,10 +51,10 @@ The debug namespace includes a number of other useful functions:
 * `debug.breakpoint()` introduces a breakpoint using `pdb`
 
 ```py
-{!examples/other.py!}
+--8<-- "examples/other.py"
 ```
 
-{{ example_html(examples/other.py) }}
+--8<-- "examples/other.html"
 
 ### Prettier print
 
@@ -66,18 +66,18 @@ To get round this *devtools* comes with prettier print, my take on pretty printi
 in `debug()`, but it can also be used directly:
 
 ```py
-{!examples/prettier.py!}
+--8<-- "examples/prettier.py"
 ```
 
-{{ example_html(examples/prettier.py) }}
+--8<-- "examples/prettier.html"
 
 For more details on prettier printing, see
 [`prettier.py`](https://github.com/samuelcolvin/python-devtools/blob/main/devtools/prettier.py).
 
 ## ANSI terminal colours
 
 ```py
-{!examples/ansi_colours.py!}
+--8<-- "examples/ansi_colours.py"
 ```
 
 For more details on ansi colours, see
@@ -95,10 +95,6 @@ Two ways to do this:
 
 ### Automatic install
 
-!!! warning
-    This is experimental, please [create an issue](https://github.com/samuelcolvin/python-devtools/issues)
-    if you encounter any problems.
-
 To install `debug` into `__builtins__` automatically, run:
 
 ```bash