Merge branch 'dev' into feature/technical-drw

wireviz · Oct 13, 2021 · 59ee742 · 59ee742
2 parents b0ab711 + a6efd28
commit 59ee742
Show file tree

Hide file tree

Showing 115 changed files with 10,333 additions and 8,730 deletions.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,6 +1,6 @@
 # Change Log
 
-## [0.3](https://github.com/formatc1702/WireViz/tree/v0.3) (202X-XX-XX)
+## [0.3](https://github.com/formatc1702/WireViz/tree/v0.3) (2021-10-11)
 
 ### New features
 
@@ -9,15 +9,26 @@
 - Add support for length units in cables and wires ([#7](https://github.com/formatc1702/WireViz/issues/7), [#196](https://github.com/formatc1702/WireViz/pull/196) (with work from [#161](https://github.com/formatc1702/WireViz/pull/161), [#162](https://github.com/formatc1702/WireViz/pull/162), [#171](https://github.com/formatc1702/WireViz/pull/171)), [#198](https://github.com/formatc1702/WireViz/pull/198), [#205](https://github.com/formatc1702/WireViz/issues/205). [#206](https://github.com/formatc1702/WireViz/pull/206))
 - Add option to define connector pin colors ([#53](https://github.com/formatc1702/WireViz/issues/53), [#141](https://github.com/formatc1702/WireViz/pull/141))
 - Remove HTML links from the input attributes ([#164](https://github.com/formatc1702/WireViz/pull/164))
+- Add harness metadata section ([#158](https://github.com/formatc1702/WireViz/issues/158), [#214](https://github.com/formatc1702/WireViz/pull/214))
+- Add support for supplier and supplier part number information ([#240](https://github.com/formatc1702/WireViz/issues/240), [#241](https://github.com/formatc1702/WireViz/pull/241/))
+- Add graph rendering options (colors, font, color name display style, ...) ([#158](https://github.com/formatc1702/WireViz/issues/158), [#214](https://github.com/formatc1702/WireViz/pull/214))
+- Add support for background colors for cables and connectors, as well as for some individual cells ([#210](https://github.com/formatc1702/WireViz/issues/210), [#219](https://github.com/formatc1702/WireViz/pull/219))
+- Add optional tweaking of the .gv output ([#215](https://github.com/formatc1702/WireViz/pull/215)) (experimental)
 
 
 ## Misc. fixes
 
+- Remove case-sensitivity issues with pin names and labels ([#160](https://github.com/formatc1702/WireViz/issues/160), [#229](https://github.com/formatc1702/WireViz/pull/229))
 - Improve type hinting ([#156](https://github.com/formatc1702/WireViz/issues/156), [#163](https://github.com/formatc1702/WireViz/pull/163))
 - Move BOM management and HTML functions to separate modules ([#151](https://github.com/formatc1702/WireViz/issues/151), [#192](https://github.com/formatc1702/WireViz/pull/192))
 - Simplify BOM code ([#197](https://github.com/formatc1702/WireViz/pull/197))
 - Bug fixes ([#218](https://github.com/formatc1702/WireViz/pull/218), [#221](https://github.com/formatc1702/WireViz/pull/221))
 
+## Known issues
+
+- Including images in the harness may lead to issues in the following cases: ([#189](https://github.com/formatc1702/WireViz/pull/189), [#220](https://github.com/formatc1702/WireViz/issues/220))
+  - When using the `-o`/`--output_file` CLI option, specifying an output path in a different directory from the input file
+  - When using the `--prepend-file` CLI option, specifying a prepend file in a different directory from the mail input file
 
 ## [0.2](https://github.com/formatc1702/WireViz/tree/v0.2) (2020-10-17)
 

diff --git a/docs/syntax.md b/docs/syntax.md
@@ -3,12 +3,6 @@
 ## Main sections
 
 ```yaml
-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)
-  ...
 connectors:  # dictionary of all used connectors
   <str>   :    # unique connector designator/name
     ...          # connector attributes (see below)
@@ -35,57 +29,17 @@ additional_bom_items:  # custom items to add to BOM
   - <bom-item>           # BOM item (see below)
   ...
 
-```
-
-## Metadata entries
-
-```yaml
-  # Meta-information describing the harness
-
-  # Each key/value pair replaces all key references in
-  # the HTML output template with the belonging value.
-  # Typical keys are 'title', 'description', and 'notes',
-  # but any key is accepted. Unused keys are ignored.
-  <key>   : <value>  # Any valid YAML syntax is accepted
-  # If no value is specified for 'title', then the
-  # output filename without extension is used.
-```
-
-## Options
-
-```yaml
-  # 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'
-
-  # Background color of other diagram elements
-  bgcolor_node: <color>        # Default = 'WH'
-  bgcolor_connector: <color>   # Default = bgcolor_node
-  bgcolor_cable: <color>       # Default = bgcolor_node
-  bgcolor_bundle: <color>      # Default = bgcolor_cable
-
-  # How to display colors as text in the diagram
-  # 'full' : Lowercase full color name
-  # 'FULL' : Uppercase full color name
-  # 'hex'  : Lowercase hexadecimal values
-  # 'HEX'  : Uppercase hexadecimal values
-  # 'short': Lowercase short color name
-  # 'SHORT': Uppercase short color name
-  # 'ger'  : Lowercase short German color name
-  # 'GER'  : Uppercase short German color name
-  color_mode: <str>            # Default = 'SHORT'
+metadata:  # dictionary of meta-information describing the harness
+  <key>   : <value>  # any number of key value pairs (see below)
+  ...
 
-  # Fontname to use in diagram and HTML output
-  fontname: <str>              # Default = 'arial'
+options:  # dictionary of common attributes for the whole harness
+  <str>   : <value>  # optional harness attributes (see below)
+  ...
 
-  # If True, show only a BOM entry reference together with basic info
-  # about additional components inside the diagram node (connector/cable box).
-  # If False, show all info about additional components inside the diagram node.
-  mini_bom_mode: <bool>        # Default = True
+tweak:  # optional tweaking of .gv output
+  ...
 ```
-
 ## Connector attributes
 
 ```yaml
@@ -100,8 +54,10 @@ additional_bom_items:  # custom items to add to BOM
   # 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
-  mpn: <str>             # manufacturer 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)
 
@@ -117,6 +73,8 @@ additional_bom_items:  # custom items to add to BOM
                      # 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
@@ -161,20 +119,26 @@ Since the auto-incremented and auto-assigned designator is not known to the user
                           #                  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>     # is assumed to be in meters
-  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
-                          # using 's' as the wire number
+  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
-  mpn: <str>             # manufacturer 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)
 
@@ -192,6 +156,8 @@ Since the auto-incremented and auto-assigned designator is not known to the user
   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
@@ -284,6 +250,56 @@ For connectors with `autogenerate: true`, a new instance, with auto-generated de
   - `<str>` to refer to a wire's label or color, if unambiguous.
 
 
+
+## Metadata entries
+
+```yaml
+  # Meta-information describing the harness
+
+  # Each key/value pair replaces all key references in
+  # the HTML output template with the belonging value.
+  # Typical keys are 'title', 'description', and 'notes',
+  # but any key is accepted. Unused keys are ignored.
+  <key>   : <value>  # Any valid YAML syntax is accepted
+  # If no value is specified for 'title', then the
+  # output filename without extension is used.
+```
+
+## Options
+
+```yaml
+  # 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'
+
+  # Background color of other diagram elements
+  bgcolor_node: <color>        # Default = 'WH'
+  bgcolor_connector: <color>   # Default = bgcolor_node
+  bgcolor_cable: <color>       # Default = bgcolor_node
+  bgcolor_bundle: <color>      # Default = bgcolor_cable
+
+  # How to display colors as text in the diagram
+  # 'full' : Lowercase full color name
+  # 'FULL' : Uppercase full color name
+  # 'hex'  : Lowercase hexadecimal values
+  # 'HEX'  : Uppercase hexadecimal values
+  # 'short': Lowercase short color name
+  # 'SHORT': Uppercase short color name
+  # 'ger'  : Lowercase short German color name
+  # 'GER'  : Uppercase short German color name
+  color_mode: <str>            # Default = 'SHORT'
+
+  # Fontname to use in diagram and HTML output
+  fontname: <str>              # Default = 'arial'
+
+  # If True, show only a BOM entry reference together with basic info
+  # about additional components inside the diagram node (connector/cable box).
+  # If False, show all info about additional components inside the diagram node.
+  mini_bom_mode: <bool>        # Default = True
+```
+
 ## BOM items and additional components
 
 Connectors (both regular, and auto-generated), cables, and wires of a bundle are automatically added to the BOM,
@@ -309,8 +325,11 @@ Parts can be added to a connector or cable in the section `<additional-component
                   # total_length     sum of lengths of each wire in the bundle
   unit: <str>
   pn: <str>            # [internal] part number
-  mpn: <str>           # manufacturer 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.
@@ -323,8 +342,35 @@ Alternatively items can be added to just the BOM by putting them in the section
   unit: <str>   
   designators: <List>
   pn: <str>            # [internal] part number
-  mpn: <str>           # manufacturer part number
   manufacturer: <str>  # manufacturer name  
+  mpn: <str>           # manufacturer part number
+  supplier: <str>      # supplier name  
+  spn: <str>           # supplier part number
+```
+
+## GraphViz tweaking (experimental)
+
+```yaml
+  # 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
+    # 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.
+    <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.
+      # Use null as new value to delete an attribute.
+
+  append: <str/list> # string or list of strings to append to the .gv output
 ```
 
 ## Colors
@@ -359,6 +405,9 @@ The following colors are understood:
 <!-- color list generated with a helper script: -->
 <!-- https://gist.github.com/formatc1702/3c93fb4c5e392364899283f78672b952 -->
 
+It is also possible to specify colors as hexadecimal RGB values, e.g. `#112233` or `#FFFF00:#009900`.
+Remember quoting strings containing a `#` in the YAML file.
+
 ## Cable color codes
 
 Supported color codes:
@@ -385,6 +434,7 @@ image:
   src: <path>        # path to the image file
   # optional parameters:
   caption: <str>     # text to display below the image
+  bgcolor: <color>   # Background color of entry in diagram component box
   width: <int>       # range: 1~65535; unit: points
   height: <int>      # range: 1~65535; unit: points
   # if only one dimension (width/height) is specified, the image is scaled proportionally.
@@ -402,7 +452,10 @@ The following attributes accept multiline strings:
 - `notes`
 - `manufacturer`
 - `mpn`
+- `supplier`
+- `spn`
 - `image.caption`
+- `tweak.append`
 
 ### Method 1
 

diff --git a/examples/demo01.bom.tsv b/examples/demo01.bom.tsv