From 38012de9d13b83861a8001792ac6a8cf2e5a8552 Mon Sep 17 00:00:00 2001 From: Leynos Date: Mon, 9 Jun 2025 02:20:13 +0100 Subject: [PATCH 1/4] Document usage and development --- README.md | 55 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 38 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index c9b2ff6..fefb43a 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,56 @@ # nixie -`nixie` is a simple command-line tool that validates Mermaid diagrams embedded in Markdown files. +`nixie` validates Mermaid diagrams embedded in Markdown files. -The CLI scans each provided file (or directory) for `mermaid` code blocks and -invokes `mermaid-cli` to verify that the diagrams can be rendered without -errors. +## Features + +- Recursively searches directories for Markdown files +- Parses `mermaid` code blocks and uses `@mermaid-js/mermaid-cli` to validate +- Runs checks concurrently for faster feedback +- Prints clear error messages for failing diagrams + +## Requirements + +- Python 3.11+ +- Node.js with `npx` and `@mermaid-js/mermaid-cli` + +## Installation + +Install the package in editable mode and set up development tools using `uv`: + +```bash +pip install -e . +uv sync --include dev +``` ## Usage ```bash -nixie path/to/file.md +nixie [--concurrency N] FILE [FILE...] ``` -Use `--concurrency` to control how many diagrams are processed in parallel. The tool relies on -Node.js and `@mermaid-js/mermaid-cli` being available on your system. +`--concurrency` controls how many diagrams are processed in parallel. Paths can +be files or directories. ## Development -Development dependencies are managed via `pyproject.toml`. After installing -[uv](https://github.com/astral-sh/uv), run: +Run formatting, linting, type checking and tests before committing: ```bash -uv sync --include dev +ruff format +ruff check +pyright +pytest ``` -This installs linters and test tools such as Ruff, Pyright, pytest and -pytest-asyncio. +The integration tests mock the CLI so Node.js is not needed during testing. -Before running the test suite, install the project in editable mode so the -package can be imported: +## Project Structure -```bash -pip install -e . -``` +- `nixie/cli.py` – command-line interface and validation logic +- `nixie/unittests/` – unit tests for helper functions +- `tests/integration/` – behavioural tests covering the CLI + +## License + +See `LICENSE` for license details. From 47091bd8018d9c46cb5569b884000bc81c34236b Mon Sep 17 00:00:00 2001 From: Leynos Date: Mon, 9 Jun 2025 02:58:03 +0100 Subject: [PATCH 2/4] Clarify uv usage and concurrency --- README.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index fefb43a..5eef3bf 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,8 @@ ## Installation -Install the package in editable mode and set up development tools using `uv`: +Install the package in editable mode and set up development tools using +[uv](https://github.com/astral-sh/uv), Astral's fast Python package manager: ```bash pip install -e . @@ -29,8 +30,18 @@ uv sync --include dev nixie [--concurrency N] FILE [FILE...] ``` -`--concurrency` controls how many diagrams are processed in parallel. Paths can -be files or directories. +`--concurrency` controls how many diagrams are processed in parallel (defaults +to the number of CPU cores or `4`). Paths can be files or directories. + +Example: + +```bash +$ nixie bad.md +Parse error on line 1: +invalid diagram +^ +Unexpected token: syntax error +``` ## Development From 05212ee81b26ac3793305ef72feead42d83649e5 Mon Sep 17 00:00:00 2001 From: Leynos Date: Mon, 9 Jun 2025 02:58:09 +0100 Subject: [PATCH 3/4] Update concurrency note --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5eef3bf..dd1b8de 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ ## Installation Install the package in editable mode and set up development tools using -[uv](https://github.com/astral-sh/uv), Astral's fast Python package manager: +[uv](https://docs.astral.sh/uv/), Astral's fast Python package manager: ```bash pip install -e . @@ -31,7 +31,8 @@ nixie [--concurrency N] FILE [FILE...] ``` `--concurrency` controls how many diagrams are processed in parallel (defaults -to the number of CPU cores or `4`). Paths can be files or directories. +to the number of CPU cores or `4` if this cannot be determined). Paths can be +files or directories. Example: From 1f337b958afb0ae58fd4889e8e3fbbde1c88d5e0 Mon Sep 17 00:00:00 2001 From: Leynos Date: Mon, 9 Jun 2025 03:15:54 +0100 Subject: [PATCH 4/4] Add PyPI installation instructions --- README.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dd1b8de..7a94a7f 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,21 @@ ## Installation -Install the package in editable mode and set up development tools using -[uv](https://docs.astral.sh/uv/), Astral's fast Python package manager: +### From PyPI + +End users can install the latest release directly from PyPI: + +```bash +pip install nixie +``` + +This provides the `nixie` command without any development extras. + +### Development Setup + +To contribute to nixie, install the package in editable mode and set up +development tools using [uv](https://docs.astral.sh/uv/), Astral's fast Python +package manager: ```bash pip install -e .