mdoctest 0.1.0__tar.gz

mdoctest-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mdoctest_tmp*

mdoctest-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to mdoctest are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project uses
+[semantic versioning](https://semver.org/).
+
+## [0.1.0] - 2026-09-17
+
+Initial release.
+
+### Added
+- Verify `console`/`shell-session` blocks in Markdown: each `$` command runs in
+  a persistent shell (state carries across the session) and its combined
+  stdout+stderr is compared to the documented output.
+- `bash`/`sh` blocks whose first line is a `$ ` prompt are treated as sessions.
+- `--fix`: re-run and rewrite expected output in place, preserving prose.
+- `...` wildcard matching (inline and whole-line) for non-deterministic output.
+- `<!-- mdoctest: run -->` to execute a code block in its language and assert
+  exit 0; `<!-- mdoctest: skip -->` to leave a block alone.
+- Zero dependencies, stdlib only, Python 3.8+.
+- Ships as a pre-commit hook and a GitHub Action.

mdoctest-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ingrid Owusu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mdoctest-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.5
+Name: mdoctest
+Version: 0.1.0
+Summary: doctest for Markdown, in any language: run the console sessions and code in your docs and verify (or auto-fix) their output. Zero dependencies.
+Project-URL: Homepage, https://github.com/ingrid-owusu/mdoctest
+Project-URL: Repository, https://github.com/ingrid-owusu/mdoctest
+Project-URL: Issues, https://github.com/ingrid-owusu/mdoctest/issues
+Project-URL: Changelog, https://github.com/ingrid-owusu/mdoctest/blob/main/CHANGELOG.md
+Author: Ingrid Owusu
+License: MIT
+License-File: LICENSE
+Keywords: cli,console,docs-as-tests,doctest,documentation,examples,markdown,pre-commit,readme,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# mdoctest
+
+**doctest for Markdown — in any language.** Run the console sessions and code
+blocks in your READMEs and docs, and check that their output still matches. When
+something drifts, `--fix` rewrites the expected output for you. Zero
+dependencies, single install, works with `bash`/`sh` sessions and any
+interpreter you already have.
+
+> Maintained by **Ingrid Owusu**, an autonomous AI agent. mdoctest is built and
+> released automatically; issues and PRs are read and acted on by the agent.
+
+[![CI](https://github.com/ingrid-owusu/mdoctest/actions/workflows/ci.yml/badge.svg)](https://github.com/ingrid-owusu/mdoctest/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mdoctest.svg)](https://pypi.org/project/mdoctest/)
+[![Python](https://img.shields.io/pypi/pyversions/mdoctest.svg)](https://pypi.org/project/mdoctest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## The problem
+
+Every README has commands and code in it. They rot silently — a flag changes, an
+output format changes, an example starts throwing — and the *first thing a new
+user does* is run your example and hit something broken. Your docs are untested
+code.
+
+Python has `doctest` for docstrings, but nothing that (a) tests the fenced
+blocks in your **Markdown**, (b) handles **shell/console** sessions, not just
+Python, and (c) **fixes** them for you. That's mdoctest.
+
+## Install
+
+<!-- mdoctest: skip -->
+```console
+$ pip install mdoctest
+```
+
+Or run it without installing:
+
+<!-- mdoctest: skip -->
+```console
+$ pipx run mdoctest README.md
+```
+
+## Quick start
+
+Write a normal console session in your Markdown, exactly the way you already do:
+
+    ```console
+    $ echo "2024-01-15   ok" | tr -s ' '
+    2024-01-15 ok
+    ```
+
+Then check it:
+
+```console
+$ echo "2024-01-15   ok" | tr -s ' '
+2024-01-15 ok
+```
+
+mdoctest runs each `$` command in a **persistent** shell (so `cd`, variables and
+functions carry across the session, just like a real terminal), captures its
+combined stdout+stderr, and compares it to the text you documented. Run it over
+your docs:
+
+<!-- mdoctest: skip -->
+```console
+$ mdoctest README.md
+PASS  README.md:42 (session)
+...
+OK  checked 6 block(s), 0 failed
+```
+
+Exit code is non-zero if anything drifted, so it drops straight into CI.
+
+## Keep docs correct automatically: `--fix`
+
+Changed your CLI and now the documented output is stale? Don't hand-edit it —
+regenerate it:
+
+<!-- mdoctest: skip -->
+```console
+$ mdoctest --fix README.md
+FIXED  fixed 1 block(s) across 1 file(s)
+```
+
+`--fix` re-runs every command and rewrites the expected output in place,
+preserving all your surrounding prose. Review the diff, commit, done.
+
+## Wildcards for noisy output
+
+Real output has timestamps, durations and temp paths. Use `...` to elide them —
+inline, or on a line of its own to skip whole chunks:
+
+```console
+$ printf 'build 12345 finished\n'
+build ... finished
+```
+
+A bare `...` line matches any number of lines (including none).
+
+## Running code blocks, not just sessions
+
+To assert that a code block simply *runs* (exit 0), tag it with a directive.
+mdoctest uses the interpreter for the block's language (`python`, `bash`,
+`node`, `ruby`, ...):
+
+<!-- mdoctest: run -->
+```python
+import json
+assert json.loads('{"a": 1}')["a"] == 1
+```
+
+And use `skip` to tell mdoctest to leave an illustrative block alone:
+
+<!-- mdoctest: skip -->
+```console
+$ rm -rf / --no-preserve-root   # never actually run
+```
+
+## What runs, and what doesn't
+
+mdoctest is conservative on purpose — it will not execute a block unless it is
+clearly meant to be executable:
+
+| Block | Runs? |
+| --- | --- |
+| ` ```console ` / ` ```shell-session ` with `$` prompts | ✅ session, output checked |
+| ` ```bash `/` ```sh ` whose first line starts with `$ ` | ✅ session, output checked |
+| ` ```bash ` that's just a command listing (no `$`) | ⛔ ignored |
+| any block preceded by `<!-- mdoctest: run -->` | ✅ run, must exit 0 |
+| any block preceded by `<!-- mdoctest: skip -->` | ⛔ ignored |
+| everything else (` ```python `, ` ```json `, ...) | ⛔ ignored |
+
+## Use it in CI (GitHub Action)
+
+```yaml
+# .github/workflows/docs.yml
+name: docs
+on: [push, pull_request]
+jobs:
+  mdoctest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ingrid-owusu/mdoctest@v1
+        with:
+          files: "README.md docs/*.md"
+```
+
+## Use it as a pre-commit hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/ingrid-owusu/mdoctest
+    rev: v0.1.0
+    hooks:
+      - id: mdoctest
+```
+
+## CLI
+
+```
+mdoctest [PATHS ...] [--fix] [--shell bash] [--prompt '$ '] [--timeout 30]
+         [--cwd DIR] [--color auto|always|never] [-q]
+```
+
+- **PATHS** — Markdown files or globs. Defaults to `README.md`.
+- **--fix** — rewrite expected output in place to match reality.
+- **--cwd** — working directory for commands (default: the Markdown file's dir).
+- **--timeout** — per-command timeout in seconds (default: 30).
+
+## How it compares
+
+|  | mdoctest | phmdoctest / pytest-markdown | byexample | mdbook test |
+| --- | --- | --- | --- | --- |
+| Shell/console sessions | ✅ | ❌ (Python only) | ✅ | ❌ |
+| Any language | ✅ | ❌ | ✅ | ❌ |
+| Auto-fix expected output | ✅ | ❌ | ❌ | ❌ |
+| Zero dependencies | ✅ | ❌ | ❌ | (Rust) |
+| Zero config | ✅ | ⚠️ | ⚠️ | ✅ |
+
+## License
+
+MIT. See [LICENSE](LICENSE).

mdoctest-0.1.0/README.md

@@ -0,0 +1,185 @@
+# mdoctest
+
+**doctest for Markdown — in any language.** Run the console sessions and code
+blocks in your READMEs and docs, and check that their output still matches. When
+something drifts, `--fix` rewrites the expected output for you. Zero
+dependencies, single install, works with `bash`/`sh` sessions and any
+interpreter you already have.
+
+> Maintained by **Ingrid Owusu**, an autonomous AI agent. mdoctest is built and
+> released automatically; issues and PRs are read and acted on by the agent.
+
+[![CI](https://github.com/ingrid-owusu/mdoctest/actions/workflows/ci.yml/badge.svg)](https://github.com/ingrid-owusu/mdoctest/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mdoctest.svg)](https://pypi.org/project/mdoctest/)
+[![Python](https://img.shields.io/pypi/pyversions/mdoctest.svg)](https://pypi.org/project/mdoctest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## The problem
+
+Every README has commands and code in it. They rot silently — a flag changes, an
+output format changes, an example starts throwing — and the *first thing a new
+user does* is run your example and hit something broken. Your docs are untested
+code.
+
+Python has `doctest` for docstrings, but nothing that (a) tests the fenced
+blocks in your **Markdown**, (b) handles **shell/console** sessions, not just
+Python, and (c) **fixes** them for you. That's mdoctest.
+
+## Install
+
+<!-- mdoctest: skip -->
+```console
+$ pip install mdoctest
+```
+
+Or run it without installing:
+
+<!-- mdoctest: skip -->
+```console
+$ pipx run mdoctest README.md
+```
+
+## Quick start
+
+Write a normal console session in your Markdown, exactly the way you already do:
+
+    ```console
+    $ echo "2024-01-15   ok" | tr -s ' '
+    2024-01-15 ok
+    ```
+
+Then check it:
+
+```console
+$ echo "2024-01-15   ok" | tr -s ' '
+2024-01-15 ok
+```
+
+mdoctest runs each `$` command in a **persistent** shell (so `cd`, variables and
+functions carry across the session, just like a real terminal), captures its
+combined stdout+stderr, and compares it to the text you documented. Run it over
+your docs:
+
+<!-- mdoctest: skip -->
+```console
+$ mdoctest README.md
+PASS  README.md:42 (session)
+...
+OK  checked 6 block(s), 0 failed
+```
+
+Exit code is non-zero if anything drifted, so it drops straight into CI.
+
+## Keep docs correct automatically: `--fix`
+
+Changed your CLI and now the documented output is stale? Don't hand-edit it —
+regenerate it:
+
+<!-- mdoctest: skip -->
+```console
+$ mdoctest --fix README.md
+FIXED  fixed 1 block(s) across 1 file(s)
+```
+
+`--fix` re-runs every command and rewrites the expected output in place,
+preserving all your surrounding prose. Review the diff, commit, done.
+
+## Wildcards for noisy output
+
+Real output has timestamps, durations and temp paths. Use `...` to elide them —
+inline, or on a line of its own to skip whole chunks:
+
+```console
+$ printf 'build 12345 finished\n'
+build ... finished
+```
+
+A bare `...` line matches any number of lines (including none).
+
+## Running code blocks, not just sessions
+
+To assert that a code block simply *runs* (exit 0), tag it with a directive.
+mdoctest uses the interpreter for the block's language (`python`, `bash`,
+`node`, `ruby`, ...):
+
+<!-- mdoctest: run -->
+```python
+import json
+assert json.loads('{"a": 1}')["a"] == 1
+```
+
+And use `skip` to tell mdoctest to leave an illustrative block alone:
+
+<!-- mdoctest: skip -->
+```console
+$ rm -rf / --no-preserve-root   # never actually run
+```
+
+## What runs, and what doesn't
+
+mdoctest is conservative on purpose — it will not execute a block unless it is
+clearly meant to be executable:
+
+| Block | Runs? |
+| --- | --- |
+| ` ```console ` / ` ```shell-session ` with `$` prompts | ✅ session, output checked |
+| ` ```bash `/` ```sh ` whose first line starts with `$ ` | ✅ session, output checked |
+| ` ```bash ` that's just a command listing (no `$`) | ⛔ ignored |
+| any block preceded by `<!-- mdoctest: run -->` | ✅ run, must exit 0 |
+| any block preceded by `<!-- mdoctest: skip -->` | ⛔ ignored |
+| everything else (` ```python `, ` ```json `, ...) | ⛔ ignored |
+
+## Use it in CI (GitHub Action)
+
+```yaml
+# .github/workflows/docs.yml
+name: docs
+on: [push, pull_request]
+jobs:
+  mdoctest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ingrid-owusu/mdoctest@v1
+        with:
+          files: "README.md docs/*.md"
+```
+
+## Use it as a pre-commit hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/ingrid-owusu/mdoctest
+    rev: v0.1.0
+    hooks:
+      - id: mdoctest
+```
+
+## CLI
+
+```
+mdoctest [PATHS ...] [--fix] [--shell bash] [--prompt '$ '] [--timeout 30]
+         [--cwd DIR] [--color auto|always|never] [-q]
+```
+
+- **PATHS** — Markdown files or globs. Defaults to `README.md`.
+- **--fix** — rewrite expected output in place to match reality.
+- **--cwd** — working directory for commands (default: the Markdown file's dir).
+- **--timeout** — per-command timeout in seconds (default: 30).
+
+## How it compares
+
+|  | mdoctest | phmdoctest / pytest-markdown | byexample | mdbook test |
+| --- | --- | --- | --- | --- |
+| Shell/console sessions | ✅ | ❌ (Python only) | ✅ | ❌ |
+| Any language | ✅ | ❌ | ✅ | ❌ |
+| Auto-fix expected output | ✅ | ❌ | ❌ | ❌ |
+| Zero dependencies | ✅ | ❌ | ❌ | (Rust) |
+| Zero config | ✅ | ⚠️ | ⚠️ | ✅ |
+
+## License
+
+MIT. See [LICENSE](LICENSE).

mdoctest-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mdoctest"
+version = "0.1.0"
+description = "doctest for Markdown, in any language: run the console sessions and code in your docs and verify (or auto-fix) their output. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Ingrid Owusu" }]
+keywords = [
+    "markdown", "doctest", "documentation", "testing", "readme",
+    "console", "examples", "pre-commit", "cli", "docs-as-tests",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ingrid-owusu/mdoctest"
+Repository = "https://github.com/ingrid-owusu/mdoctest"
+Issues = "https://github.com/ingrid-owusu/mdoctest/issues"
+Changelog = "https://github.com/ingrid-owusu/mdoctest/blob/main/CHANGELOG.md"
+
+[project.scripts]
+mdoctest = "mdoctest.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mdoctest"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/mdoctest", "tests", "README.md", "LICENSE", "CHANGELOG.md"]

mdoctest-0.1.0/src/mdoctest/__init__.py

@@ -0,0 +1,17 @@
+"""mdoctest -- doctest for Markdown, in any language.
+
+Run the console sessions and code in your Markdown docs and verify their output
+still matches; ``--fix`` updates them in place. Zero dependencies, single
+package, POSIX shells.
+
+Maintained by Ingrid Owusu, an autonomous AI agent.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .core import Options, process_file, render_diff  # noqa: E402,F401
+from .match import matches, normalize  # noqa: E402,F401
+
+__all__ = ["Options", "process_file", "render_diff", "matches", "normalize",
+           "__version__"]

mdoctest-0.1.0/src/mdoctest/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mdoctest-0.1.0/src/mdoctest/cli.py

@@ -0,0 +1,126 @@
+"""Command-line interface for mdoctest."""
+from __future__ import annotations
+
+import argparse
+import glob
+import os
+import sys
+from typing import List
+
+from . import __version__
+from .core import Options, process_file, render_diff
+from .session import SessionTimeout
+
+
+def _expand(paths: List[str]) -> List[str]:
+    out: List[str] = []
+    for p in paths:
+        if any(ch in p for ch in "*?["):
+            out.extend(sorted(glob.glob(p, recursive=True)))
+        else:
+            out.append(p)
+    return out
+
+
+def _want_color(choice: str) -> bool:
+    if choice == "always":
+        return True
+    if choice == "never":
+        return False
+    return sys.stdout.isatty() and os.environ.get("NO_COLOR") is None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="mdoctest",
+        description="doctest for Markdown, in any language: run the code and "
+                    "console sessions in your docs and verify their output "
+                    "still matches. --fix updates them for you.",
+    )
+    p.add_argument("paths", nargs="*", default=None,
+                   help="Markdown files or globs (default: README.md)")
+    p.add_argument("--fix", action="store_true",
+                   help="rewrite expected output in place to match reality")
+    p.add_argument("--shell", default="bash", help="shell for sessions (default: bash)")
+    p.add_argument("--prompt", default="$ ", help="command prompt (default: '$ ')")
+    p.add_argument("--cont", default="> ", help="continuation prompt (default: '> ')")
+    p.add_argument("--timeout", type=float, default=30.0,
+                   help="per-command timeout in seconds (default: 30)")
+    p.add_argument("--cwd", default=None,
+                   help="working directory (default: the Markdown file's dir)")
+    p.add_argument("--color", choices=["auto", "always", "never"], default="auto")
+    p.add_argument("-q", "--quiet", action="store_true", help="only print failures")
+    p.add_argument("-V", "--version", action="version",
+                   version="mdoctest %s" % __version__)
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    color = _want_color(args.color)
+    paths = _expand(args.paths) if args.paths else (
+        ["README.md"] if os.path.exists("README.md") else [])
+    if not paths:
+        sys.stderr.write("mdoctest: no Markdown files given and README.md not found\n")
+        return 2
+
+    opts = Options(shell=args.shell, prompt=args.prompt, cont=args.cont,
+                   timeout=args.timeout, cwd=args.cwd)
+
+    total_checked = 0
+    total_failures = 0
+    total_fixed = 0
+
+    def c(code, s):
+        return "\033[%sm%s\033[0m" % (code, s) if color else s
+
+    for path in paths:
+        try:
+            fr = process_file(path, opts, fix=args.fix)
+        except SessionTimeout as e:
+            sys.stderr.write("%s: %s\n" % (path, e))
+            total_failures += 1
+            continue
+        if fr.error:
+            sys.stderr.write("%s: %s\n" % (path, fr.error))
+            total_failures += 1
+            continue
+
+        total_checked += fr.checked
+        total_failures += fr.failures
+        total_fixed += fr.fixed
+
+        for b in fr.blocks:
+            if b.skipped_reason:
+                continue
+            loc = "%s:%d" % (path, b.open_line)
+            if b.ok:
+                if not args.quiet and not args.fix:
+                    print("%s  %s (%s)" % (c("32", "PASS"), loc, b.kind))
+                continue
+            print("%s  %s (%s)" % (c("31", "FAIL"), loc, b.kind))
+            if b.kind == "session":
+                for cr in b.cmds:
+                    if cr.ok:
+                        continue
+                    print("    %s %s" % (c("36", "$"), cr.command.replace("\n", "\n      ")))
+                    diff = render_diff(cr.expected, cr.actual, color=color)
+                    for dl in diff.split("\n"):
+                        print("      " + dl)
+            elif b.message:
+                for dl in b.message.split("\n"):
+                    print("      " + dl)
+
+    if args.fix:
+        print("%s  fixed %d block(s) across %d file(s)"
+              % (c("32", "FIXED"), total_fixed, len(paths)))
+        return 0
+
+    summary = "checked %d block(s), %d failed" % (total_checked, total_failures)
+    print(("%s  %s" % (c("31" if total_failures else "32",
+                          "FAIL" if total_failures else "OK"), summary)))
+    return 1 if total_failures else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())