Continuous documentation

docs/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Change Log
 
+## [0.3](https://github.com/formatc1702/WireViz/tree/v0.3) (202X-XX-XX)
+
+### New features
+
+- Allow referencing a cable's/bundle's wires by color or by label ([#70](https://github.com/formatc1702/WireViz/issues/70), [#169](https://github.com/formatc1702/WireViz/issues/169), [#193](https://github.com/formatc1702/WireViz/issues/193), [#194](https://github.com/formatc1702/WireViz/pull/194))
+- Allow additional BOM items within components ([#50](https://github.com/formatc1702/WireViz/issues/50), [#115](https://github.com/formatc1702/WireViz/pull/115))
+- 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))
+
+
+## Misc. fixes
+
+- 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))
+- Bug fixes ([#218](https://github.com/formatc1702/WireViz/pull/218), [#221](https://github.com/formatc1702/WireViz/pull/221))
+
+
 ## [0.2](https://github.com/formatc1702/WireViz/tree/v0.2) (2020-10-17)
 
 ### Backward incompatible changes
@@ -16,6 +34,7 @@ See the [syntax description](syntax.md) for details.
 
 
 ### New features
+
 - Add bidirectional AWG/mm2 conversion ([#40](https://github.com/formatc1702/WireViz/issues/40), [#41](https://github.com/formatc1702/WireViz/pull/41))
 - Add support for part numbers ([#11](https://github.com/formatc1702/WireViz/pull/11), [#114](https://github.com/formatc1702/WireViz/issues/114), [#121](https://github.com/formatc1702/WireViz/pull/121))
 - Add support for multicolored wires ([#12](https://github.com/formatc1702/WireViz/issues/12), [#17](https://github.com/formatc1702/WireViz/pull/17), [#96](https://github.com/formatc1702/WireViz/pull/96), [#131](https://github.com/formatc1702/WireViz/issues/131), [#132](https://github.com/formatc1702/WireViz/pull/132))

docs/syntax.md

@@ -43,16 +43,24 @@ additional_bom_items:  # custom items to add to BOM
   notes: <str>   
 
   # product information (all optional)
-  pn: <str>            # [internal] part number
-  mpn: <str>           # manufacturer part number
-  manufacturer: <str>  # manufacturer name
+  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
+  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
 
+  # 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)
   style: <style>         # may be set to simple for single pin connectors
   show_name: <bool>      # defaults to true for regular connectors,
@@ -108,9 +116,12 @@ Since the auto-incremented and auto-assigned designator is not known to the user
   notes: <str>   
 
   # product information (all optional)
-  pn: <str>            # [internal] part number
-  mpn: <str>           # manufacturer part number
-  manufacturer: <str>  # manufacturer name
+  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
+  additional_components: # additional components
+    - <additional-component> # additional component (see below)
 
   # conductor information
   # the following combinations are permitted:
@@ -123,9 +134,12 @@ Since the auto-incremented and auto-assigned designator is not known to the user
   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
+
   # rendering information (all optional)
-  show_name: <bool>       # defaults to true
-  show_wirecount: <bool>  # defaults to true
+  show_name: <bool>         # defaults to true
+  show_wirecount: <bool>    # defaults to true
+  show_wirenumbers: <bool>  # defaults to true for cables; false for bundles
 
 ```
 
@@ -162,6 +176,8 @@ connections:
 - The maximum number of items is unlimited.
 - Items must alternatingly belong to the `connectors` and the `cables` sections.
 - When a connection set defines multiple parallel connections, the number of specified `<pin>`s and `<wire>`s for each component in the set must match. When specifying only one designator, one is auto-generated for each connection of the set.
+- `<pin>` may reference a pin's unique ID (as per the connector's `pins` attribute, auto-numbered from 1 by default) or its label (as per `pinlabels`).
+- `<wire>` may reference a wire's number within a cable/bundle, its label (as per `wirelabels`) or, if unambiguous, its color.
 
 ### Single connections
 
@@ -210,29 +226,45 @@ For connectors with `autogenerate: true`, a new instance, with auto-generated de
 
   - `<int>` to refer to a specific wire, using its number.
   - `<int>-<int>` auto-expands to a range.
+  - `<str>` to refer to a wire's label or color, if unambiguous.
 
 
-## BOM items
+## 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`.
+Additional items can be added to the BOM as either part of a connector or cable or on their own.
 
-<!-- unless the `ignore_in_bom` attribute is set to `true` (#115) -->
+Parts can be added to a connector or cable in the section `<additional-component>` which will also list them in the graph.
 
-Additional BOM entries can be generated in the sections marked `<bom-item>` above.
+```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
+                  # 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
+  mpn: <str>           # manufacturer part number
+  manufacturer: <str>  # manufacturer name  
+```
 
-<!-- BOM items inside connectors/cables are not implemented yet, but should be soon (#50) -->
+Alternatively items can be added to just the BOM by putting them in the section `<bom-item>` above.
 
 ```yaml
 -
   description: <str>              
-  qty: <int/str>  # when used in the additional_bom_items section:
-                  # <int>            manually specify qty.
-                  # when used within a component:
-                  # <int>            manually specify qty.
-                  # pincount         match number of pins of connector
-                  # wirecount        match number of wires of cable/bundle
-                  # connectioncount  match number of connected pins
   # 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