warehack.ing/WireViz
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Correct indentation and <...> brackets

Browse Source
This commit is contained in:
Martin Rieder 2024-07-02 01:56:12 +02:00
parent f5e4c061c1
commit a6504fd6c9
1 changed files with 171 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

344
docs/syntax.md
View File

@ -31,150 +31,153 @@ Their respective attribute assignments need to be indented using space character
Make sure they are aligned correctly in the document hierarchy, i.e. by two spaces for each level!
```yaml
connectors: # dictionary of all used connectors
<str> : # unique connector designator/name
... # connector attributes (see below)
<str> :
...
...
connectors: # dictionary of all used connectors
<str>: # unique connector designator/name
<str>: <...> # connector attributes (see below)
<str>:
<str>: <...>
<...>
cables: # dictionary of all used cables and wires
<str> : # unique cable designator/name
... # cable attributes (see below)
<str> :
...
...
cables: # dictionary of all used cables and wires
<str>: # unique cable designator/name
<str>: <...> # cable attributes (see below)
<str>:
<str>: <...>
<...>
connections: # list of all connections to be made
# between cables and connectors
connections: # list of all connection sets (see below)
-
... # connection set (see below)
- <...> # <connector> or <cable>
- <...> # <cable> or <connector>
-
...
...
- <...>
<...>
additional_bom_items: # custom items to add to BOM
- <bom-item> # BOM item (see below)
...
- <bom-item> # BOM item (see below)
<str>: <...>
metadata: # dictionary of meta-information describing the harness
<key> : <value> # any number of key value pairs (see below)
...
metadata: # dictionary of meta-information describing the harness
<key>: <value> # any number of key value pairs (see below)
<...>
options: # dictionary of common attributes for the whole harness
<str> : <value> # optional harness attributes (see below)
...
options: # dictionary of common attributes for the whole harness
<str>: <value> # optional harness attributes (see below)
<...>
tweak: # optional tweaking of .gv output
...
tweak: # optional tweaking of .gv output
<...>
```
## Connector attributes
```yaml
<str> : # unique connector designator/name
# general information about a connector (all optional)
type: <str>
subtype: <str>
color: <color> # see below
image: <image> # see below
notes: <str>
connectors:
<str>: # unique connector designator/name
# general information about a connector (all optional)
type: <str>
subtype: <str>
color: <color> # see below
image: <image> # see below
notes: <str>
# product information (all optional)
ignore_in_bom: <bool> # if set to true the connector is not added to the BOM
pn: <str> # [internal] part number
manufacturer: <str> # manufacturer name
mpn: <str> # manufacturer part number
supplier: <str> # supplier name
spn: <str> # supplier part number
additional_components: # additional components
- <additional-component> # additional component (see below)
# product information (all optional)
ignore_in_bom: <bool> # if set to true the connector is not added to the BOM
pn: <str> # [internal] part number
manufacturer: <str> # manufacturer name
mpn: <str> # manufacturer part number
supplier: <str> # supplier name
spn: <str> # supplier part number
additional_components: # additional components
- <additional-component> # additional component (see below)
# pinout information
# at least one of the following must be specified
pincount: <int> # if omitted, is set to length of specified list(s)
pins: <List> # if omitted, is autofilled with [1, 2, ..., pincount]
pinlabels: <List> # if omitted, is autofilled with blanks
# pinout information
# at least one of the following must be specified
pincount: <int> # if omitted, is set to length of specified list(s)
pins: <List> # if omitted, is autofilled with [1, 2, ..., pincount]
pinlabels: <List> # if omitted, is autofilled with blanks
# pin color marks (optional)
pincolors: <List> # list of colors to be assigned to the respective pins;
# if list length is lower than connector pinout,
# no color marks will be added to remaining pins
# pin color marks (optional)
pincolors: <List> # list of colors to be assigned to the respective pins;
# if list length is lower than connector pinout,
# no color marks will be added to remaining pins
# rendering information (all optional)
bgcolor: <color> # Background color of diagram connector box
bgcolor_title: <color> # Background color of title in diagram connector box
style: <style> # may be set to simple for single pin connectors
show_name: <bool> # defaults to true for regular connectors,
# false for simple connectors
show_pincount: <bool> # defaults to true for regular connectors
# false for simple connectors
hide_disconnected_pins: <bool> # defaults to false
# rendering information (all optional)
bgcolor: <color> # Background color of diagram connector box
bgcolor_title: <color> # Background color of title in diagram connector box
style: <style> # may be set to simple for single pin connectors
show_name: <bool> # defaults to true for regular connectors,
# false for simple connectors
show_pincount: <bool> # defaults to true for regular connectors
# false for simple connectors
hide_disconnected_pins: <bool> # defaults to false
# loops
loops: <List> # every list item is itself a list of exactly two pins
# on the connector that are to be shorted
# loops
loops: <List> # every list item is itself a list of exactly two pins
# on the connector that are to be shorted
```
## Cable attributes
```yaml
<str> : # unique cable designator/name
# general information about a connector (all optional)
category: <category> # may be set to bundle;
# generates one BOM item for every wire in the bundle
# instead of a single item for the entire cable;
# renders with a dashed outline
type: <str>
gauge: <int/float/str> # allowed formats:
# <int/float> mm2 is understood
# <int> AWG is understood
# <int/float> is assumed to be mm2
# <str> custom units and formats are allowed
# but unavailable for auto-conversion
show_equiv: <bool> # defaults to false; can auto-convert between mm2 and AWG
# and display the result when set to true
length: <int/float>[ <unit>] # <int/float> is assumed to be in meters unless <unit> is specified
# e.g. length: 2.5 -> assumed to be 2.5 m
# or length: 2.5 ft -> "ft" is used as the unit
# Units are not converted during BOM generation;
# different units result in separate BOM entries.
shield: <bool/color> # defaults to false
# setting to true will display the shield as a thin black line
# using a color (see below) will render the shield in that color
# A shield can be accessed by using 's' as the wire ID
color: <color> # see below
image: <image> # see below
notes: <str>
cables:
<str>: # unique cable designator/name
# general information about a connector (all optional)
category: <category> # may be set to bundle;
# generates one BOM item for every wire in the bundle
# instead of a single item for the entire cable;
# renders with a dashed outline
type: <str>
gauge: <int/float/str> # allowed formats:
# <int/float> mm2 is understood
# <int> AWG is understood
# <int/float> is assumed to be mm2
# <str> custom units and formats are allowed
# but unavailable for auto-conversion
show_equiv: <bool> # defaults to false; can auto-convert between mm2 and AWG
# and display the result when set to true
length: <int/float>[ <unit>] # <int/float> is assumed to be in meters unless <unit> is specified
# e.g. length: 2.5 -> assumed to be 2.5 m
# or length: 2.5 ft -> "ft" is used as the unit
# Units are not converted during BOM generation;
# different units result in separate BOM entries.
shield: <bool/color> # defaults to false
# setting to true will display the shield as a thin black line
# using a color (see below) will render the shield in that color
# A shield can be accessed by using 's' as the wire ID
color: <color> # see below
image: <image> # see below
notes: <str>
# product information (all optional)
ignore_in_bom: <bool> # if set to true the cable or wires are not added to the BOM
pn: <str> # [internal] part number
manufacturer: <str> # manufacturer name
mpn: <str> # manufacturer part number
supplier: <str> # supplier name
spn: <str> # supplier part number
additional_components: # additional components
- <additional-component> # additional component (see below)
# product information (all optional)
ignore_in_bom: <bool> # if set to true the cable or wires are not added to the BOM
pn: <str> # [internal] part number
manufacturer: <str> # manufacturer name
mpn: <str> # manufacturer part number
supplier: <str> # supplier name
spn: <str> # supplier part number
additional_components: # additional components
- <additional-component> # additional component (see below)
# conductor information
# the following combinations are permitted:
# wirecount only no color information is specified
# colors only wirecount is inferred from list length
# wirecount + color_code colors are auto-generated based on the specified
# color code (see below) to match the wirecount
# wirecount + colors colors list is trimmed or repeated to match the wirecount
wirecount: <int>
colors: <List> # list of colors (see below)
color_code: <str> # one of the supported cable color codes (see below)
# conductor information
# the following combinations are permitted:
# wirecount only no color information is specified
# colors only wirecount is inferred from list length
# wirecount + color_code colors are auto-generated based on the specified
# color code (see below) to match the wirecount
# wirecount + colors colors list is trimmed or repeated to match the wirecount
wirecount: <int>
colors: <List> # list of colors (see below)
color_code: <str> # one of the supported cable color codes (see below)
wirelabels: <List> # optional; one label for each wire
wirelabels: <List> # optional; one label for each wire
# rendering information (all optional)
bgcolor: <color> # Background color of diagram cable box
bgcolor_title: <color> # Background color of title in diagram cable box
show_name: <bool> # defaults to true
show_wirecount: <bool> # defaults to true
show_wirenumbers: <bool> # defaults to true for cables; false for bundles
# rendering information (all optional)
bgcolor: <color> # Background color of diagram cable box
bgcolor_title: <color> # Background color of title in diagram cable box
show_name: <bool> # defaults to true
show_wirecount: <bool> # defaults to true
show_wirenumbers: <bool> # defaults to true for cables; false for bundles
```
@ -197,7 +200,7 @@ connections:
- <component> # Each connection set is itself a list of items
- <component> # Items must alternatingly belong to the connectors and cables sections
# Arrows may be used instead of cables
-...
- <...>
- # example (single connection)
- <connector>: <pin> # attach one pin of the connector
@ -225,7 +228,7 @@ connections:
# use double line arrow (==, <==, <==>, ==>)
- <connector>
...
<...>
```
### Single connections
@ -293,7 +296,7 @@ connections:
- <arrow> # ==, <==, <==> or ==>
- <connector>
-
- ...
- <...>
- <connector>: [<pin>, ...] # designator and pinlist (pinlist is ignored)
# useful when combining arrows and wires
- <arrow> # ==, <==, <==> or ==>
@ -359,7 +362,7 @@ Even if a component is not connected to any other components, it must be mention
```yaml
connectors:
X1: # this connector will not be connected to any other components
...
<...>
connections:
-
@ -373,7 +376,7 @@ If any component is defined in the `connectors` or `cables` sections but not ref
## Metadata entries
```yaml
# Meta-information describing the harness
metadata: # Meta-information describing the harness
# Each key/value pair replaces all key references in
# the HTML output template with the belonging value.
@ -388,8 +391,8 @@ See [HTML Output Templates](../src/wireviz/templates/) for how metadata entries
## Options
```yaml
# Common attributes for the whole harness.
# All entries are optional and have default values.
options: # Common attributes for the whole harness.
# All entries are optional and have default values.
# Background color of diagram and HTML output
bgcolor: <color> # Default = 'WH'
@ -426,51 +429,52 @@ See [HTML Output Templates](../src/wireviz/templates/) for how metadata entries
## BOM items and additional components
Connectors (both regular, and auto-generated), cables, and wires of a bundle are automatically added to the BOM,
unless the `ignore_in_bom` attribute is set to `true`.
Connectors (both regular, and auto-generated), cables, and wires of a bundle are automatically added to the BOM, unless the `ignore_in_bom` attribute is set to `true`.
Additional items can be added to the BOM as either part of a connector or cable or on their own.
Parts can be added to a connector or cable in the section `<additional-component>` which will also list them in the graph.
```yaml
-
type: <str> # type of additional component
# all the following are optional:
subtype: <str> # additional description (only shown in bom)
qty: <int/float> # qty to add to the bom (defaults to 1)
qty_multiplier: <str> # multiplies qty by a feature of the parent component
# when used in a connector:
# pincount number of pins of connector
# populated number of populated positions in a connector
# unpopulated number of unpopulated positions
# when used in a cable:
# wirecount number of wires of cable/bundle
# terminations number of terminations on a cable/bundle
# length length of cable/bundle
# total_length sum of lengths of each wire in the bundle
unit: <str>
pn: <str> # [internal] part number
manufacturer: <str> # manufacturer name
mpn: <str> # manufacturer part number
supplier: <str> # supplier name
spn: <str> # supplier part number
bgcolor: <color> # Background color of entry in diagram component box
additional_components:
-
type: <str> # type of additional component
# all the following are optional:
subtype: <str> # additional description (only shown in bom)
qty: <int/float> # qty to add to the bom (defaults to 1)
qty_multiplier: <str> # multiplies qty by a feature of the parent component
# when used in a connector:
# pincount number of pins of connector
# populated number of populated positions in a connector
# unpopulated number of unpopulated positions
# when used in a cable:
# wirecount number of wires of cable/bundle
# terminations number of terminations on a cable/bundle
# length length of cable/bundle
# total_length sum of lengths of each wire in the bundle
unit: <str>
pn: <str> # [internal] part number
manufacturer: <str> # manufacturer name
mpn: <str> # manufacturer part number
supplier: <str> # supplier name
spn: <str> # supplier part number
bgcolor: <color> # Background color of entry in diagram component box
```
Alternatively items can be added to just the BOM by putting them in the section `<bom-item>` above.
```yaml
-
description: <str>
# all the following are optional:
qty: <int/float> # qty to add to the bom (defaults to 1)
unit: <str>
designators: <List>
pn: <str> # [internal] part number
manufacturer: <str> # manufacturer name
mpn: <str> # manufacturer part number
supplier: <str> # supplier name
spn: <str> # supplier part number
additional_bom_items:
-
description: <str>
# all the following are optional:
qty: <int/float> # qty to add to the bom (defaults to 1)
unit: <str>
designators: <List>
pn: <str> # [internal] part number
manufacturer: <str> # manufacturer name
mpn: <str> # manufacturer part number
supplier: <str> # supplier name
spn: <str> # supplier part number
```
## GraphViz tweaking (experimental)
@ -479,23 +483,17 @@ This feature is experimental and might change or be removed in future versions.
```yaml
# Optional tweaking of the .gv output.
# This feature is experimental and might change
# or be removed in future versions.
tweak: # Optional tweaking of the .gv output.
override: # dict of .gv entries to override
# Each entry is identified by its leading string
# in lines beginning with a TAB character.
# The leading string might be in "quotes" in
# the .gv output. This leading string must be
# Each entry is identified by its leading string in lines beginning with a TAB character.
# The leading string might be in "quotes" in the .gv output. This leading string must be
# followed by attributes in [square brackets].
# Entries with an attribute containing HTML are
# not supported.
# Entries with an attribute containing HTML are not supported.
<str>: # leading string of .gv entry
<str> : <str/null> # attribute and its new value
# Any number of attributes can be overridden
# for each entry. Attributes not already existing
# in the entry will be appended to the entry.
<str>: <str/null> # attribute and its new value
# Any number of attributes can be overridden for each entry.
# Attributes not already existing in the entry will be appended to the entry.
# Use null as new value to delete an attribute.
append: <str/list> # string or list of strings to append to the .gv output
@ -630,4 +628,4 @@ See [yaml-multiline.info](https://yaml-multiline.info/) for more information.
## Inheritance
[YAML anchors and references](https://blog.daemonl.com/2016/02/yaml.html) are useful for defining and referencing information that is used more than once in a file, e.g. when using defining multiple connectors of the same type or family. See [Demo 02](../examples/demo02.yml) for an example.
[YAML anchors and references](https://blog.daemonl.com/2016/02/yaml.html) are useful for defining and referencing information that is used more than once in a file, e.g. when using multiple connectors of the same type or family. See [Demo 02](../examples/demo02.yml) for an example.