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