Skip to content

Latest commit

 

History

History
88 lines (70 loc) · 3.78 KB

generated-markdown.md

File metadata and controls

88 lines (70 loc) · 3.78 KB

Generated Markdown

Parts of this repository's markdown are generated from the registries, so a name or a description has exactly one home: the registration that owns it. Read this before editing a catalog table in the README, before adding an entry to a catalog, or when cargo test fails on a markdown file you did not touch.

CONTRIBUTING.md carries the one rule that binds every contributor (never edit inside a region). This file is the mechanism and the commands. The code side is documented at the top of crates/darkly/src/docs_md/mod.rs.

Regions

A file opts a span of itself in by bracketing it with comments, which render as nothing:

<!-- darkly:catalog-table catalog=effects -->
…generated…
<!-- /darkly:catalog-table -->

Markdown is not the only target. AppStream metainfo is XML and its comments are the same <!-- -->, so packaging/art.darkly.Darkly.metainfo.xml needed no grammar of its own. A desktop entry has no such syntax and uses # instead:

# darkly:app-desktop-entry
Comment=…
# /darkly:app-desktop-entry

Markdown is never read with the # form, or every heading would be a comment body. Syntax::of in crates/darkly/src/docs_md/mod.rs decides by extension, and is the one place to edit to admit a new file type.

packaging/app.json is generated too, and is the exception to all of this: JSON has no comment syntax to hide a marker in, so the whole file is written rather than a span of it. It exists because desktop/forge.config.js is JavaScript with no YAML parser, and so cannot read the source everything else renders from.

Never edit inside a region: the next sync overwrites it. Every name and description in one belongs to the thing that owns it, so a typo in the README's effects table is fixed on the registration in crates/darkly/src/gpu/effects/, and the app's own summary, description, categories and keywords are fixed in crates/darkly/product.yaml. The metainfo's <releases> block is not a region: it is generated from the v* tags by scripts/metainfo-releases.sh, refreshed and committed after each release, and refilled at build time (see docs/versioning.md).

cargo sync-docs              # refill every region
cargo sync-docs -- --check   # report drift, write nothing

tests/docs_md.rs fails if a committed region is stale, so the ordinary test suite is the gate: run cargo sync-docs when you have touched a registration and it will tell you what it rewrote. A new kind of region is a new file in crates/darkly/src/docs_md/fragments/ exporting pub fn register(): nothing else is touched.

Preview stills

Preview stills are the one part that is not automatic: they need a GPU and land in the repository as binaries, so they are rendered deliberately when a catalog gains or loses an entry. tests/docs_md.rs fails on a region linking to an image that is not in the checkout, which is how you find out.

cargo run --release -p darkly --features testing --bin render_docs -- \
  --stills --catalog effects

Catalog graphics

A catalog-graphic region embeds a rendered picture of a catalog instead of a table of it, as the README's effects section does. The picture is a Svelte component in frontend/src/graphics/, rasterized by resvg rather than a browser; what that costs a component is documented at the top of the runner. npm test re-renders each one and fails if the committed image is stale.

cargo run -q -p darkly --bin export-docs -- --out target/docs/metadata.json
node frontend/scripts/render-doc-graphics.mjs --metadata target/docs/metadata.json