Skip to content

DEV.md

Latest commit

 

History

History
63 lines (39 loc) · 2.18 KB

DEV.md

File metadata and controls

63 lines (39 loc) · 2.18 KB
Raw

Development

Prerequisites

  • Rust toolchain
  • Python 3.10+
  • maturin
  • fastship>=0.0.11, installed by pip install -e '.[dev]'

Building

For local development, build and install the extension into your environment:

maturin develop

ship-rs-build builds the distributable wheel. The xhtmlmd command is a Python console script (python/xhtmlmd/__main__.py) over the to_xhtml API; there is no separate Rust binary.

Testing

pytest -q

All tests are Python (tests/), run against the built extension; there are no cargo test unit tests.

Docs

python tools/gen_docs.py
python tools/gen_docs.py --check

Source rewriting

The Python rewrite API gets edit nodes from the native edit_nodes function. During the block parse, ContainerBuilder records the line ranges of paragraphs, headings, and pipe tables, including those nested in containers. Opaque blocks such as code, raw HTML, block math, and grid tables produce no editable ranges. The inline edit scanner runs only over those ranges and shares the parser's math, code-span, image-destination, and link-label helpers.

Native offsets refer to normalized UTF-8 input. The Python wrapper maps them back to character offsets in the original string, including CRLF input, invokes callbacks in source order, and applies their replacements in reverse order. Edit nodes should be added only for constructs with exact contiguous source ranges; they do not require or imply a source-mapped semantic AST.

Release

Publishing is handled by GitHub Actions in .github/workflows/ci.yml and is triggered by pushing a tag matching v*.

Release flow is: release first, then bump.

  1. Confirm tests pass:
pytest -q

  1. Confirm the release version in Cargo.toml ([package].version). pyproject.toml gets the Python package version from Cargo via dynamic = ["version"].

  2. Tag that commit and push the tag:

ship-rs-release
  1. After pushing the release tag, run ship-rs-bump, commit the Cargo.toml version bump, and push to main without a tag.

No local wheel build is required for release. CI builds wheels for Linux and macOS, creates a GitHub Release, and publishes to PyPI.