Skip to content

Release v0.3.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 07 Sep 12:07
· 1026 commits to main since this release
v0.3.0
64b8005

TopMark v0.3.0 — Release Notes

🚀 A major milestone introducing a stable public API surface, new CLI subcommands, and an expanded documentation system.

✨ Added

  • Stable public API surface under topmark.api and topmark.registry.
    • Functions: check(), strip(), version(), get_filetype_info(), get_processor_info().
    • Result/metadata types: Outcome, FileResult, RunResult, FileTypeInfo, ProcessorInfo, WritePolicy.
    • Structural protocols for plugins: PublicFileType, PublicHeaderProcessor.
    • Registry facade for read-only discovery of file types, processors, and bindings.
    • Public API tests and snapshot (tests/api/public_api_snapshot.json) to guard semver stability.
  • Docs overhaul for API & internals:
    • New docs/api/public.md (stable public API) and docs/api/internals.md (internals landing).
    • New docs/gen_api_pages.py generator for per-module internals with breadcrumbs and first-line summaries.
    • MkDocs wiring via mkdocs-gen-files & autorefs.
    • Local typing stub typings/mkdocs_gen_files/__init__.pyi to avoid plugin requirement in dev envs.
    • Stability policy & semver guardrails added to CONTRIBUTING.
  • CLI improvement:
    • Re-export cli at topmark.cli for from topmark.cli import cli.
  • New processors command:
    • Lists registered header processors and their file types.
    • Options: --long, --format default|json|ndjson|markdown.
    • Shared Click-free markdown_table helper for Markdown output.

🔄 Changed

  • CLI refactor:
    • Explicit subcommands and unified input planning.
    • Migrated away from custom typed_* helpers to native Click decorators.
    • Standardized exit policy & summaries.
    • Subcommands include: check, strip, dump-config, filetypes, init-config, show-defaults, version.
  • Config layer:
    • Now accepts ArgsLike mapping (CLI-free).
    • No longer requires a Click namespace in public API entry points.
  • Docs:
    • Split monolithic API page into public vs internals.
    • Added generator-based internals.
    • Fixed breadcrumb/link regressions.
    • Aligned pre-commit and mdformat settings with new docs layout.
  • Output formatting:
    • Adopt Click’s built-in styling.
    • Unified Markdown views for filetypes & processors.
  • Tooling:
    • Bumped pre-commit hooks (ruff v0.12.12, pyright v1.1.405).
    • Project version set to 0.3.0 in pyproject.toml and CONTRIBUTING.md.

⚠️ Breaking

  • The public API surface is explicitly defined from this release forward and will follow semver.
    • Low-level registries and internals remain unstable.
  • Implicit default CLI command removed:
    • topmark --… → use topmark check --….
  • Legacy typed_* Click helpers removed.

🐛 Fixed

  • Correct enum comparisons for OutputFormat across commands.
  • Markdown rendering branches trigger consistently; format handling unified.
  • Docs warnings around internal links/breadcrumbs resolved.
  • Configs aligned with api/public.md.

📦 Installing / Upgrading

pip install -U topmark

Links

Assets 2
Loading