Skip to content

supdoc v0.3.0

Choose a tag to compare

@aidenzepp aidenzepp released this 04 Nov 14:17
· 196 commits to main since this release
29196fd

supdoc v0.3.0 adds code blocks: it checks the fenced code in your Markdown and in Rust doc comments, keeps excerpts in sync with the code they quote, and formats and lints blocks with your project's own tools. Linking works as before, and the lockfile keeps schema_version = 2.

Code blocks

Turn the feature on with a [features.code-blocks] table, and each language with its own table: [features.code-blocks.rust], .shell or .python. A block in a language without a table is counted as not checked. [features.code-blocks] has its own include and exclude, which default to the top-level ones, so you can link everywhere and check code only in, say, docs/ and skills/.

  • Excerpts that can't drift. ```rust from(src/lib.rs#Limits.resolve) makes a block exactly that symbol's text. You can repeat from(...); the excerpts are joined in order by a blank line. A stale block is code-block-stale, and supdoc fix rewrites it.
  • Hand-written blocks you want to keep honest. uses(PATH#SYMBOL) tracks a symbol like a link, in any language. supdoc check flags the block for review when the symbol changes, and supdoc update records the change.
  • Formatting with rustfmt (under your pinned toolchain and edition), shfmt (with your shell dialect), and ruff format or black. Unformatted blocks are code-block-unformatted, and supdoc fix applies the formatter's output. Output that would close the fence or edit outside the block is refused.
  • Linting with ruff check for Python and shellcheck for shell. Each finding is code-block-lint at the doc's own line and column.
  • Explicit switches, never automatic. supdoc never rewrites a block behind your back or invents a skip.
    • Per block: ignore(<reason>), lint(off: <reason>), format(off: <reason>), or lint(full) / format(full) to override the config.
    • Per tool: [features.code-blocks.<language>.<tool>] lint/format = "full" | "off".
    • A step that didn't run is always counted and named, for example "1 lint not run (clippy needs trust)".
  • Safe on untrusted docs. Tools are found on PATH, never inside the checkout. Each one runs in its own process group, from an empty private directory, with a cleared environment, the block on stdin, capped output and a per-block timeout ([limits] code-block-timeout). Ctrl-C or SIGTERM stops every tool, and supdoc then ends by that signal.
  • Fast. Results are cached outside the checkout, and distinct blocks run in parallel.

Not in this release

  • Clippy for Rust blocks is built, but it runs only in the project tier, which arrives with supdoc trust. Compiling an untrusted block needs an OS-level file sandbox first. Until then, a Rust block's lint step reads "not run (clippy needs trust)".
  • rustdoc-style hidden # lines aren't supported: a # line is ordinary code. Write context visibly, or excerpt it with from(...).

New codes

  • code-block-stale, -source-missing, -uses-new, -uses-changed, -uses-obsolete;
  • code-block-unformatted, -parse, -lint;
  • code-block-tool-missing, -tool-failed, -tool-timeout;
  • code-block-not-checked, -unknown-attribute, -missing-reason, -fix-unsafe.

Every one has a help that names a command or value.

Also fixed

  • A termination signal always ends supdoc by that signal: no output after it, and no tool left running (#208, #210).