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.
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 nothingtests/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 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 effectsA 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