Documentation sheets · SoftForge Electronics Designer

A documentation sheet is an ordinary .kicad_sch sheet of the project that holds draft views of the board (top / bottom assembly, fabrication, detail, section, 3D render), live tables (BOM, drill table, layer stack-up, fabrication notes, revisions), balloons numbered by the BOM, dimensions and notes, and a title block bound to the project. KiCad opens and prints the sheets unchanged; a sidecar <sheet>.kicad_doc.json next to each one remembers where every element comes from, so the extension can regenerate it from the board. The requirements are on the board (PRJ-2, completed by PRJ-9).

A walkthrough with the sample project#

Open examples/sample-project/blinky.kicad_sch. Besides the Root and Timer schematics, the hierarchy has two A3 documentation sheets, printed after the schematics:

Assembly (assembly.kicad_sch): the TOP VIEW (3:1, the largest scale of the ladder 5:1 · 4:1 · 3.5:1 · 3:1 · 2.5:1 · 2:1 … whose layout fits the A3 sheet) with the part references and pin-1 marks, the board width and height dimensions and one balloon per part (11), each numbered with its line of the BILL OF MATERIALS table next to it (Item, Qty, Reference, Value, Footprint, MPN, DNP — the whole project, grouped like kicad-cli sch export bom); the BOTTOM VIEW (mirrored; the sample has no parts underneath, so the view shows the bottom copper — through-hole pads, tracks, vias — and the drilled holes instead of an empty outline); DETAIL A at 6:1 (twice the main scale) of the densest corner of the board (U1 with C3 and C4), with its callout circle on the top view; a REVISIONS table. The title block shows the project’s title with the sheet name, its revision and company (${TITLE}, ${REVISION} … stay KiCad variables where KiCad resolves them).
Fabrication (fabrication.kicad_sch): the F.Cu and B.Cu layers with the board outline (both seen from the top) with a drill symbol at every hole, the DRILL TABLE (one symbol per hole size and plating, counts, total), the LAYER STACK-UP from Board Setup, the FABRICATION NOTES (material, thickness, copper, finish, mask and silk colours, minimum track, clearance and hole) and a 3D VIEW (ISO) rendered by the headless renderer, the board moved to the middle of its frame. Without Chromium the 3D view is a placeholder frame saying why.

Each sheet’s elements are KiCad groups named softforge_doc:<id> (KiCad 10 format), so in Eeschema a whole view moves as one. KiCad 8 and 9 have no schematic groups (their parsers refuse a (group …) in a schematic), so in sheets of those formats the extension writes only KiCad 8 grammar and finds every element by the uuids it gave its graphics (a prefix derived from the sheet and the element id, which KiCad keeps when it re-saves the file); graphics of an element the sidecar no longer knows are found the same way and pruned. When KiCad 10 upgrades such a sheet, the next refresh adds the groups. A group removed in KiCad (Ungroup) is put back the same way.

Text is written as KiCad schematic text when its angle is 0° or 90° (the only angles schematic text has: KiCad snaps any other angle to 0°); text at any other angle — the value of an aligned dimension, a footprint reference at 45° in a view — is written as stroke-font polylines laid out with KiCad’s own metrics, so it prints along its angle, kept upright. Table cells longer than their column (automatic columns are at most 50 mm wide, TableDef maxColumnWidth) wrap on spaces exactly as KiCad breaks text-box lines, and their row grows; a word longer than the column keeps the column as wide as the word.

The documentation editor#

A documentation sheet opens in the schematic editor like any other sheet; the extension adds:

Document tab (left panel): the Document tree lists the schematic sheets and the documentation sheets with their page in the PDF set; every sheet — schematic sheets too — can be dragged, or moved with the up / down buttons, to change the print order (kept in the root sheet’s sidecar). Under it, the Views list of the current sheet: every view, table, balloon, dimension and note with its type icon, the board revision it was generated from and a stale badge when the board changed since. Clicking a row selects the element on the canvas; hovering a balloon highlights its part and its BOM row. Buttons: new sheet, export the set, refresh all. A sheet without a sidecar offers Make this a documentation sheet.
Documentation tab (right panel), three tabs: View (caption, source board, revision, update mode On board save / Manual, type, scale presets 1:1 · 2:1 · 4:1 · 1:2 …, style assembly / fabrication / realistic / outline, position, layer checklist, references, values, pin-1 marks, courtyards, mirror, board dimensions, drill symbols, hide DNP; camera and image size for 3D renders; label, parent and region for details and sections; kind, columns, BOM scope / group by / fields / DNP / sort for tables; reference and BOM line for balloons), Sheet (paper, default board, title-block binding) and Document (print order, export format, output and Sheets: all of them or one). Every change regenerates the element as one undoable edit. Orphan balloons (their part left the BOM) are listed as warnings.
Documentation flyout in the tool bar: Draft view, Detail, Section, 3D render, Layer stack, Drill table, BOM table, Balloon, Auto-balloon, Dimension, Note, Refresh all. Views and tables open a small options dialog (type / style / scale / layers, camera, BOM scope and fields), then one click on the sheet places them. A detail is a region dragged on a view, then a click to place it; a section is two clicks on a view for the cut line, then a click; a balloon is a click on a part, then a click where the balloon goes; a dimension is two clicks on a view. Auto-balloon on a view that already has balloons leaves them where they are (also after a renumber when the BOM changes) and places only the balloons of parts that have none, on the free spots of the rings around the view nearest to each part.

Section views draw every layer at its true thickness times the view’s scale (copper and mask are thin bands, labelled on the right with leaders; plated hole walls are 25 µm). Blind, buried and micro vias ((via blind|micro … (layers a b))) cut and plate only the layers of their span and are labelled BLIND VIA F.Cu–In1.Cu Ø0.25, BURIED VIA …, MICROVIA …, prefixed with the HDI span’s name when the board’s <board>.kicad_flex.json defines via spans.

Refreshing after a board change#

Move a part on the board and save: the views and board tables whose update mode is On board save regenerate (softforge.edsnx.documentation.autoRefresh, on by default; sheets open in an editor get an undoable edit, closed ones are rewritten). The same happens when another program — KiCad itself — saves the board: a file watcher on the .kicad_pcb files regenerates the sheets (or, with autoRefresh off, or while the board has unsaved edits in the editor, only marks them stale). Until then, and for views set to Manual (the 3D render), a stale badge marks what no longer matches the board. Editing a sidecar by hand marks the elements whose definition changed stale too (each element keeps a hash of the definition it was drawn from), and the next refresh redraws them. Electronics Designer: Refresh documentation from the board (or edsnx doc refresh assembly.kicad_sch) regenerates every stale element: the part is redrawn where it now is in every view, its balloon stays where it was and its leader follows the part, tables whose content did not change (the drill table when only a part moved) are left byte-identical. edsnx doc status <sheet> lists what is stale.

Exporting the set#

Electronics Designer: Export documentation set (or edsnx doc export blinky.kicad_sch --format pdf) prints the whole project into one PDF with kicad-cli: every sheet in the order kept in the root sheet’s sidecar (blinky.kicad_doc.json order; schematic sheets it does not list come first, documentation sheets it does not list last), with one bookmark per sheet. SVG and DXF give one file per sheet. To export one sheet only, pick it in the command’s sheet list (or the Document tab’s Sheets), or edsnx doc export blinky.kicad_sch --format svg --sheet assembly.kicad_sch (a sheet file, file name or sheet name; several comma-separated). The Plot dialog has the same export as its Documentation set row. KiCad’s own Plot prints the same sheets in page-number order.

Making your own#

Electronics Designer: New documentation sheet (edsnx doc new-sheet) adds an empty A3 sheet to the hierarchy; insert views and tables from the editor’s insert bar or with edsnx doc insert-view / insert-table / auto-balloon. The two sample sheets come from presets in src/doc/sample.ts (assemblySheetPreset, fabricationSheetPreset) that work on any board: they pick the largest scale of the drafting ladder that fits (trying other block orders before giving a scale up), find the densest region for the detail view and pack the blocks on the paper without overlaps, clear of the title block. npx tsx src/cli/sampleProject.ts --docs <project dir> regenerates the sample’s two sheets.