netviz documentation

Everything netviz can do, arranged by what you are trying to get done. Start with the table: find the row that describes your problem and follow the link. If you have never run netviz before, getting-started.md is the one to read first — or spend two minutes in the live demo first, which needs nothing installed.

This whole documentation set is also published, with those demos beside it, at https://blechschmidt.github.io/netviz/.

If you want to…

The pages, by kind

Guides — read once, front to back

• getting-started.md — install netviz and Graphviz, build a three-device inventory by hand, validate it, render it, then interrogate it. Ends with the editor setup that gives you completion and inline errors.
• inventory-layout.md — how files become namespaces, how references resolve, which files are read, the element kinds, and how to declare a 48-port switch without typing 48 interfaces.
• importing.md — bootstrap the first inventory from LLDP, ip -j addr or the cabling spreadsheet you already keep, then converge on it by hand.
• rendering.md — the ten layers, the filters, namespace collapsing and link bundling, icon themes, labelling, stored arrangements, interactivity, and what each output format is good for.
• styling.md — spec.style and kind: theme: the colour and shape vocabulary, the selectors, the four-rung precedence ladder, the two bundled themes, and how to make it the inventory's default rather than a flag you have to remember.
• validation.md — the three passes, severities, --strict, the four ways to suppress a rule, and how to read a finding.
• ci.md — netviz validate and netviz test as gates: the JSON envelope, SARIF and code scanning, inline annotations, JUnit, the two GitHub Actions, the reusable workflow that publishes the diagram to Pages, pre-commit, GitLab.
• commands/test.md — kind: testsuite documents and the eleven assertions netviz test grades. Validation says whether the files cohere; this says whether the network still does what somebody built it to do.
• format.md — the canonical form netviz fmt writes, and why each decision in it is the way it is.
• editing.md — the write path: what an operation is, what its inverse is, how a rename finds every reference, and the two gates between an edit and the disk. netviz apply and the web editor are both built on it.
• commands/plan.md — the diff engine: stable addresses, structural rename detection, the order a changeset has to run in, plan files and the state hash, and how a capture becomes a proposal. commands/apply.md executes the result against the files.
• commands/review.md — the change written up for a reviewer: what it does to the network, what it broke that was not already broken, and the drawing. ci.md is the bot built on it.
• commands/converge.md — the other half of the loop: drift joined to the configuration emitters, as a per-device plan. What a change is, the dependency order, how the management path is worked out and what makes a change disruptive, the maintenance batches, and the boundary netviz does not cross — it writes scripts and never opens a session to a device.
• ipam.md — utilisation, free space, the next free block, aggregation and conflicts, with the arithmetic spelled out.
• paths.md — how the trace works, what counts as a hop, several paths and none, and how to draw the answer.
• export.md — the eight operational artefacts, what each guarantees, what each drops, and how names are folded; then the seven configuration dialects, which generate the file a device would actually run from.
• ansible.md — the Ansible integration: the shipped netviz.netviz collection, a dynamic inventory whose host variables are queries, and the lookup that lets a template ask the network for the address it is about to write down.
• drawio.md — the draw.io round trip: what the exported diagram carries, what a draw.io user may and may not safely change, and how an edited file comes back as a reviewable changeset.
• commands/report.md — the as-built document: what each page carries, how a namespace becomes a site, why the output is byte-stable, and how to edit the layout. example-report/ is one, committed and browsable.
• configuration.md — netviz.toml: per-inventory render defaults, named profiles, precedence, and how to see what resolved.
• docker.md — the image and the compose file: the CLI, the live preview and the browser editor in a container, what they mount, what they publish, and who owns the files they write.
• lsp.md — netviz lsp in VS Code, Neovim, Helix and Emacs: what each capability is answered by, how it degrades when the editor opens a lone file, and where the published JSON Schema stops being enough.

Reference — look things up

• commands/ — one page per command, with every flag. The tables are generated from the CLI, so they cannot drift.
• query.md — the selector language: the grammar, the attribute vocabulary, the traversal forms and a cookbook of ten worked queries. One expression answers netviz query, --select on six commands, an assert: query and the editor's search box.
• nql.md — the relational language, for the questions a predicate cannot ask: joins along the schema, and answers shaped as objects and arrays of objects. Why it is EdgeQL-shaped rather than SQL- or Cypher-shaped, its grammar, its type graph, and a cookbook.
• schema-reference.md — every field of every kind, with types, defaults and its YANG counterpart. Generated from the models.
• validation-rules.md — every rule, with what triggers it, why it exists, how to fix it and how to suppress it. This is where a finding's help link lands, so its anchors are part of netviz's interface.
• schema.md — the normative specification. Numbered sections and NV-* rule ids that code and diagnostics quote; the anchors are stable on purpose.
• yang-mapping.md — which standard each field comes from, and what netviz deliberately does not model.

For contributors

• architecture.md — the pipeline (load_tree → validate → build_graph → filter/aggregate → renderers), which module owns each stage, what each may assume, and the invariants not to break. Also: using netviz as a library.
• ../CONTRIBUTING.md — dev setup, the gates, and step-by-step recipes for adding a validation rule or a renderer.
• testing.md — the property-based and fuzz testing, the Hypothesis profiles, and how to reproduce a failure.
• follow-ups.md — the running list of known gaps and deliberate deferrals, each with the reasoning that deferred it.
• releasing.md — what a 0.x version number promises, which surfaces are public API and which are internal, how a breaking change has to be recorded, and the mechanics of cutting a release.
• ../CHANGELOG.md — what changed in each release, and what you have to do about it.

How the documentation is kept honest

Documentation this size only stays correct if something fails when it stops being correct. tests/test_docs.py asserts that:

• every relative link and #anchor in every Markdown file in the repository resolves;
• every command and every flag the CLI has appears in commands/, and no documented flag has been removed — the tables are generated from Click by tools/gen_docs.py and compared against what is committed;
• every rule in netviz/rules.py has a section in validation-rules.md with the right severity, aliases and anchor, and appears in the index in validation.md;
• every field of every model has an entry in schema-reference.md;
• every fenced console example that invokes netviz is either executed, and its transcript compared byte for byte, or explicitly marked non-executable with a reason — see tools/check_examples.py.

So an example in these pages is not an illustration of what netviz used to do. It is either a test, or it says why it is not.