### Install Documentation (Linux/Unix)

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/README.adoc

Use this command to install the documentation to the default /usr prefix on Linux/Unix-like systems.

```bash
mkdir build; cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
make install
```

--------------------------------

### Compile Documentation to HTML (Example)

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/translating/translation_instructions.adoc

Example of compiling the 'cvpcb' manual into Italian HTML format.

```bash
make cvpcb_html_it
```

--------------------------------

### Install Documentation (macOS)

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/README.adoc

Use this command to install the documentation to the /Library/Application Support/kicad prefix on macOS.

```bash
mkdir build; cd build
cmake -DCMAKE_INSTALL_PREFIX="/Library/Application Support/kicad" ..
make install
```

--------------------------------

### Install Fedora Dependencies

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/README.adoc

Installs dependencies required for building KiCad documentation on Fedora.

```bash
sudo dnf install -y cmake fontconfig po4a rubygem-asciidoctor npm git wqy-microhei-fonts
sudo npm install -g puppeteer --unsafe-perm=true
sudo npm install -g @asciidoctor/core asciidoctor-web-pdf --unsafe-perm=true
```

--------------------------------

### Install Arch/Manjaro Dependencies

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/README.adoc

Installs dependencies for building KiCad documentation on Arch/Manjaro Linux.

```bash
sudo pacman -S asciidoctor fontconfig po4a cmake gettext \
perl-unicode-linebreak source-highlight ttf-freefont wqy-microhei

yay -S asciidoctor-web-pdf ttf-vlgothic
```

--------------------------------

### PADS Netlist Output Example

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/eeschema/eeschema_advanced.adoc

Example of the PADS netlist file generated after applying the XSLT stylesheet. This shows the structure of component and net information.

```text
*PADS-PCB*
*PART*
P1 unknown
U2 unknown
U1 unknown
C1 unknown
R1 unknown
*NET*
*SIGNAL* GND
U1.7
C1.2
U2.7
P1.4
*SIGNAL* VCC
R1.1
U1.14
U2.4
U2.1
U2.14
P1.1
*SIGNAL* N-4
U1.2
U2.3
*SIGNAL* /SIG_OUT
P1.2
U2.5
U2.2
*SIGNAL* /CLOCK_IN
R1.2
C1.1
U1.1
P1.3

*END*
```

--------------------------------

### Install Debian/Ubuntu Dependencies

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/README.adoc

Installs necessary packages for building KiCad documentation on Debian/Ubuntu systems. Requires about 1.5GiB of space.

```bash
sudo apt-get install cmake ruby npm ninja-build fontconfig \
fonts-freefont-ttf fonts-wqy-microhei fonts-vlgothic gettext \
git make po4a source-highlight libunicode-linebreak-perl

sudo gem install asciidoctor

sudo npm i -g @asciidoctor/core asciidoctor-pdf --unsafe-perm
```

--------------------------------

### idf2vrml Usage Example

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/pcbnew/pcbnew_advanced.adoc

Demonstrates how to invoke the idf2vrml tool to convert IDF Board files into a VRML model for visualization. This example specifically generates KiCad-friendly VRML output with a specified scale factor.

```bash
./idf2vrml -f input.emn -s 0.3937008 -k
```

--------------------------------

### Build KiCad Docs with Ninja

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/README.adoc

Builds the KiCad documentation using CMake and Ninja for accelerated compilation. Ninja must be installed separately.

```bash
cd kicad-doc
mkdir build
cd build
cmake -G Ninja ..
ninja
```

--------------------------------

### OrcadPCB2 Netlist Output Example

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/eeschema/eeschema_advanced.adoc

This is an example of the OrcadPCB2 netlist file format generated by Eeschema. It shows component information, including reference designators, values, and pin connections with net names.

```netlist
( { Eeschema Netlist Version 1.1  29/08/2010 21:07:51
eeschema (2010-08-28 BZR 2458)-unstable}
 ( 4C6E2141 $noname P1 CONN_4
  (  1 VCC )
  (  2 /SIG_OUT )
  (  3 /CLOCK_IN )
  (  4 GND )
 )
 ( 4C6E20BA $noname U2 74LS74
  (  1 VCC )
  (  2 /SIG_OUT )
  (  3 N-04 )
  (  4 VCC )
  (  5 /SIG_OUT )
  (  6 ? )
  (  7 GND )
  ( 14 VCC )
 )
 ( 4C6E20A6 $noname U1 74LS04
  (  1 /CLOCK_IN )
  (  2 N-04 )
  (  7 GND )
  ( 14 VCC )
 )
 ( 4C6E2094 $noname C1 CP
  (  1 /CLOCK_IN )
  (  2 GND )
 )
 ( 4C6E208A $noname R1 R
  (  1 VCC )
  (  2 /CLOCK_IN )
)
*

```

--------------------------------

### KiCad Netlist Example

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/eeschema/eeschema_generating_outputs.adoc

This is a full example of a KiCad netlist generated from a schematic. It includes design information, component definitions, and properties.

```kicad_netlist
(export (version "E")
  (design
    (source "/usr/share/kicad/demos/simulation/sallen_key/sallen_key.kicad_sch")
    (date "Sun 01 May 2022 03:14:05 PM EDT")
    (tool "Eeschema (6.0.4)")
    (sheet (number "1") (name "/") (tstamps "")
      (title_block
        (title)
        (company)
        (rev)
        (date)
        (source "sallen_key.kicad_sch")
        (comment (number "1") (value ""))
        (comment (number "2") (value ""))
        (comment (number "3") (value ""))
        (comment (number "4") (value ""))
        (comment (number "5") (value ""))
        (comment (number "6") (value ""))
        (comment (number "7") (value ""))
        (comment (number "8") (value ""))
        (comment (number "9") (value "")))))
  (components
    (comp (ref "C1")
      (value "100n")
      (libsource (lib "sallen_key_schlib") (part "C") (description ""))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-00005789077d"))
    (comp (ref "C2")
      (value "100n")
      (fields
        (field (name "Fieldname") "Value")
        (field (name "SpiceMapping") "1 2")
        (field (name "Spice_Primitive") "C"))
      (libsource (lib "sallen_key_schlib") (part "C") (description ""))
      (property (name "Fieldname") (value "Value"))
      (property (name "Spice_Primitive") (value "C"))
      (property (name "SpiceMapping") (value "1 2"))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-00005789085b"))
    (comp (ref "R1")
      (value "1k")
      (fields
        (field (name "Fieldname") "Value")
        (field (name "SpiceMapping") "1 2")
        (field (name "Spice_Primitive") "R"))
      (libsource (lib "sallen_key_schlib") (part "R") (description ""))
      (property (name "Fieldname") (value "Value"))
      (property (name "SpiceMapping") (value "1 2"))
      (property (name "Spice_Primitive") (value "R"))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-0000578906ff"))
    (comp (ref "R2")
      (value "1k")
      (fields
        (field (name "Fieldname") "Value")
        (field (name "SpiceMapping") "1 2")
        (field (name "Spice_Primitive") "R"))
      (libsource (lib "sallen_key_schlib") (part "R") (description ""))
      (property (name "Fieldname") (value "Value"))
      (property (name "SpiceMapping") (value "1 2"))
      (property (name "Spice_Primitive") (value "R"))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-000057890691"))
    (comp (ref "U1")
      (value "AD8051")
      (fields
        (field (name "Spice_Lib_File") "ad8051.lib")
        (field (name "Spice_Model") "AD8051")
        (field (name "Spice_Netlist_Enabled") "Y")
        (field (name "Spice_Primitive") "X"))
      (libsource (lib "sallen_key_schlib") (part "Generic_Opamp") (description ""))
      (property (name "Spice_Primitive") (value "X"))
      (property (name "Spice_Model") (value "AD8051"))
      (property (name "Spice_Lib_File") (value "ad8051.lib"))
      (property (name "Spice_Netlist_Enabled") (value "Y"))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-00005788ff9f"))
    (comp (ref "V1")
      (value "AC 1")
      (libsource (lib "sallen_key_schlib") (part "VSOURCE") (description ""))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-000057336052"))
    (comp (ref "V2")
      (value "DC 10")
      (fields
        (field (name "Fieldname") "Value")
        (field (name "Spice_Node_Sequence") "1 2")
        (field (name "Spice_Primitive") "V"))
      (libsource (lib "sallen_key_schlib") (part "VSOURCE") (description ""))
      (property (name "Fieldname") (value "Value"))
      (property (name "Spice_Primitive") (value "V"))
      (property (name "Spice_Node_Sequence") (value "1 2"))
      (property (name "Sheetname") (value ""))
      (property (name "Sheetfile") (value "sallen_key.kicad_sch"))
      (sheetpath (names "/") (tstamps "/"))
      (tstamps "00000000-0000-0000-0000-0000578900ba"))
    (comp (ref "V3")
      (value "DC 10")
      (fields
        (field (name "Fieldname") "Value")
        (field (name "Spice_Node_Sequence") "1 2")
```

--------------------------------

### Example: BOM CSV Grouped Extra Script Usage

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/eeschema/eeschema_generating_outputs.adoc

Demonstrates how to specify additional fields for the bom_csv_grouped_extra script to include in the BOM output.

```bash
<path to script>/bom_csv_grouped_extra.py "%I" "%O.csv" "MPN"
```

--------------------------------

### Get Help for PCB Subcommand

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/cli/cli.adoc

Run this command to display usage information for the 'pcb' subcommand. This helps in understanding available options for PCB operations.

```bash
kicad-cli pcb -h
```

--------------------------------

### KiCad Custom Rules Version Header

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/pcbnew/pcbnew_advanced.adoc

The custom rules file must start with a version header. This example shows the header for KiCad 10.0.

```kicad_rules
(version 1)
```

--------------------------------

### Create Language PO File and Update

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/translating/translation_instructions.adoc

Creates an empty PO file for a new language and updates it using CMake and Make. Replace NN with the language code and YOUR-CHOSEN-MANUAL with the manual's directory name.

```bash
touch src/YOUR-CHOSEN-MANUAL/po/NN.po
mkdir build
cd build
cmake ..
make YOUR-CHOSEN-MANUAL_updatepo_NN
```

--------------------------------

### Build KiCad Docs with Make

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/README.adoc

Builds the KiCad documentation using CMake and Make. Navigate to the 'kicad-doc' directory first.

```bash
cd kicad-doc
mkdir build
cd build
cmake ..
make
```

--------------------------------

### Install git-whistles

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/translating/translation_instructions.adoc

Installs the git-whistles gem, which provides the git merge-po command for handling PO file merges.

```bash
sudo gem install git-whistles
```

--------------------------------

### Cadstar Output Example

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/eeschema/eeschema_advanced.adoc

This is an example of the Cadstar netlist output generated by the XSLT transformation. It shows the header, component list, and net connections in the Cadstar format.

```text
.HEA
.TIM 21/08/2010 08:12:08
.APP "eeschema (2010-08-09 BZR 2439)-unstable"
.ADD_COM P1 "CONN_4"
.ADD_COM U2 "74LS74"
.ADD_COM U1 "74LS04"
.ADD_COM C1 "CP"
.ADD_COM R1 "R"


.ADD_TER U1.7 "GND"
.TER     C1.2
         U2.7
         P1.4
.ADD_TER R1.1 "VCC"
.TER     U1.14
         U2.4
         U2.1
         U2.14
         P1.1
.ADD_TER U1.2 "N-4"
.TER     U2.3
.ADD_TER P1.2 "/SIG_OUT"
.TER     U2.5
         U2.2
.ADD_TER R1.2 "/CLOCK_IN"
.TER     C1.1
         U1.1
         P1.3

.END
```

--------------------------------

### Example KiCad Database Library Configuration

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/eeschema/eeschema_advanced.adoc

This JSON file defines a KiCad database library, including connection details and mappings for symbol fields. Save this with a .kicad_dbl extension.

```json
{
    "meta": {
        "version": 0
    },
    "name": "My Database Library",
    "description": "A database of components",
    "globally_unique_keys": false,
    "source": {
        "type": "odbc",
        "dsn": "",
        "username": "",
        "password": "",
        "timeout_seconds": 2,
        "connection_string": ""
    },
    "libraries": [
        {
            "name": "Resistors",
            "table": "Resistors",
            "key": "Part ID",
            "symbols": "Symbols",
            "footprints": "Footprints",
            "fields": [
                {
                    "column": "MPN",
                    "name": "MPN",
                    "visible_on_add": false,
                    "visible_in_chooser": true,
                    "show_name": true,
                    "inherit_properties": true
                },
                {
                    "column": "Value",
                    "name": "Value",
                    "visible_on_add": true,
                    "visible_in_chooser": true,
                    "show_name": false
                }
            ],
            "properties": {
                "description": "Description",
                "footprint_filters": "Footprint Filters",
                "keywords": "Keywords",
                "exclude_from_bom": "No BOM",
                "exclude_from_board": "Schematic Only"
            }
        }
    ]
}
```

--------------------------------

### Assertion Constraint Example

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/pcbnew/pcbnew_advanced.adoc

Provides an example of an assertion constraint, which checks if a boolean expression is true. If the expression evaluates to false, a DRC error is generated, enforcing specific design conditions.

```adoc
(constraint assertion (condition "A.Net == 'GND'"))
```

--------------------------------

### Text Markup Syntax Examples

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/pcbnew/pcbnew_editing.adoc

Demonstrates the markup syntax for various text formatting options including superscripts, subscripts, overbars, and project/built-in text variables.

```adoc
text^{superscript}
```

```adoc
text~subscript~
```

```adoc
~{text}
```

```adoc
${variable}
```

```adoc
${refdes:field}
```

--------------------------------

### Configure Documentation Formats Option

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/CMakeLists.txt

Sets a cache variable to specify which output formats to build, such as 'html' or 'pdf'.

```cmake
set( BUILD_FORMATS "html;pdf" CACHE STRING "Specify which output formats to build html/pdf" )
```

--------------------------------

### Update Gem System

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/translating/translation_instructions.adoc

Updates the RubyGems system, which may be necessary before installing or reinstalling gems.

```bash
sudo gem update --system
```

--------------------------------

### Run API Server

Source: https://gitlab.com/kicad/services/kicad-doc/-/blob/master/src/cli/cli.adoc

Starts the KiCad IPC API server in headless mode. Scripts using the IPC API can attach to this server. An optional project or file can be pre-loaded.

```bash
kicad-cli api-server [--help] [--socket SOCKET_PATH] PROJECT_OR_FILE
```