wireviz · formatc1702 · May 12, 2024 · Oct 11, 2021 · Oct 11, 2021 · Oct 22, 2020
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,17 +1,44 @@
 # Change Log
 
+## [0.4](https://github.com/formatc1702/WireViz/tree/v0.4) (2024-XX-XX)
+
+### Backward-incompatible changes
+- New syntax for autogenerated components ([#184](https://github.com/wireviz/WireViz/issues/184), [#186](https://github.com/wireviz/WireViz/pull/186))
+  - Components that are not referenced in any connection set will not be rendered. Instead, a warning will be output in the console. ([#328](https://github.com/wireviz/WireViz/issues/328), [#332](https://github.com/wireviz/WireViz/pull/332))
+- New command line interface ([#244](https://github.com/wireviz/WireViz/pull/244)). Run `wireviz --help` for details 
+  - The path specified with the `-o`/`--output-dir` option no longer includes the filename (without extension) of the generated files. Use the `-O`/`--output-name` option to specify a different filename for the generated files.
+- The `.gv` file is no longer included as a default output format (only as an intermediate file during processing) unless specified with the new `-f` option described below.
+
+
+### New features
+
+- Allow mates between connectors ([#134](https://github.com/wireviz/WireViz/issues/134), [#186](https://github.com/wireviz/WireViz/pull/186))
+- Improve technical drawing output ([#74](https://github.com/wireviz/WireViz/pull/74), [#32](https://github.com/wireviz/WireViz/issues/32), [#239](https://github.com/wireviz/WireViz/pull/239))
+- Embed images in SVG output ([#189](https://github.com/wireviz/WireViz/pull/189))
+- Add ability to choose output formats using the `-f`/`--format` command line option ([#60](https://github.com/wireviz/WireViz/issues/60))
+- Add option to multiply additional component quantity by number of unpopulated positions on connector ([#298](https://github.com/wireviz/WireViz/pull/298))
+
+### Misc. fixes
+- Use `isort` and `black` for cleaner code and easier merging ([#248](https://github.com/wireviz/WireViz/pull/248))
+- Code improvements ([#246](https://github.com/wireviz/WireViz/pull/246), [#250](https://github.com/wireviz/WireViz/pull/250))
+- Bug fixes ([#264](https://github.com/wireviz/WireViz/pull/264), [#318](https://github.com/wireviz/WireViz/pull/318))
+- Minor adjustments ([#256](https://github.com/wireviz/WireViz/pull/256))
+
+
 ## [0.3.2](https://github.com/formatc1702/WireViz/tree/v0.3.2) (2021-11-27)
 
 ### Hotfix
 
-- Adjust GraphViz generation code for compatibility with v0.18 of the `graphviz` Python package ([#258](https://github.com/formatc1702/WireViz/issues/258), [#262](https://github.com/formatc1702/WireViz/pull/261))
+- Adjust GraphViz generation code for compatibility with v0.18 of the `graphviz` Python package ([#258](https://github.com/formatc1702/WireViz/issues/258), [#261](https://github.com/formatc1702/WireViz/pull/261))
+
 
 ## [0.3.1](https://github.com/formatc1702/WireViz/tree/v0.3.1) (2021-10-25)
 
 ### Hotfix
 
 - Assign generic harness title when using WireViz as a module and not specifying an output file name ([#253](https://github.com/formatc1702/WireViz/issues/253), [#254](https://github.com/formatc1702/WireViz/pull/254))
 
+
 ## [0.3](https://github.com/formatc1702/WireViz/tree/v0.3) (2021-10-11)
 
 ### New features
@@ -23,20 +50,20 @@
 - 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 graph rendering options (background colors, fontname, 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
+### 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
+### 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

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -25,6 +25,7 @@ When contributing to this repository, please [submit a new issue](https://github
 1. Create a new feature branch on top of the `dev` branch.
 1. Commit your code changes to this feature branch.
 1. Push the changes to your fork.
+1. Please format your code using [`isort`](https://pycqa.github.io/isort/) and [`black`](https://black.readthedocs.io) before submitting.
 1. Submit a new pull request, using `dev` as the base branch.
   - If your code changes or extends the WireViz YAML syntax, be sure to update the [syntax description document](https://github.com/formatc1702/WireViz/blob/dev/docs/syntax.md) in your PR.
 1. Please include in the PR description (and optionally also in the commit message body) a reference (# followed by issue number) to the issue where the suggested changes are discussed.

diff --git a/docs/README.md b/docs/README.md
@@ -4,6 +4,7 @@
 [![PyPI - Version](https://img.shields.io/pypi/v/wireviz.svg?colorB=blue)](https://pypi.org/project/wireviz/)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/wireviz.svg?)](https://pypi.org/project/wireviz/)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/wireviz)](https://pypi.org/project/wireviz/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 ## Summary
 
@@ -81,10 +82,11 @@ Output file:
 
 [Source](../examples/demo02.yml) - [Bill of Materials](../examples/demo02.bom.tsv)
 
-### Tutorial and example gallery
+### Syntax, tutorial and example gallery
 
-See the [tutorial page](../tutorial/readme.md) for sample code,
-as well as the [example gallery](../examples/readme.md) to see more of what WireViz can do.
+Read the [syntax description](syntax.md) to learn about WireViz' features and how to use them.
+
+See the [tutorial page](../tutorial/readme.md) for sample code, as well as the [example gallery](../examples/readme.md) to see more of what WireViz can do.
 
 
 ## Usage
@@ -125,7 +127,7 @@ If you would like to contribute to this project, make sure you read the [contrib
 $ wireviz ~/path/to/file/mywire.yml
 ```
 
-This will output the following files
+Depending on the options specified, this will output some or all of the following files:
 
 ```
 mywire.gv         GraphViz output
@@ -135,17 +137,16 @@ mywire.bom.tsv    BOM (bill of materials) as tab-separated text file
 mywire.html       HTML page with wiring diagram and BOM embedded
 ```
 
-#### Command line options
-
-- `--prepend-file <FILE>` to prepend an additional YAML file. Useful for part libraries and templates shared among multiple cables/harnesses.
-- `-o <OUTPUT>` or `--output_file <OUTPUT>` to generate output files with a name different from the input file.
-- `-V` or `--version` to display the WireViz version.
-- `-h` or `--help` to see a summary of the usage help text.
-
+Wildcards in the file path are also supported to process multiple files at once, e.g.:
+```
+$ wireviz ~/path/to/files/*.yml
+```
 
-### Syntax description
+To see how to specify the output formats, as well as additional options, run:
 
-A description of the WireViz YAML input syntax can be found [here](syntax.md).
+```
+$ wireviz --help
+```
 
 
 ### (Re-)Building the example projects

diff --git a/docs/syntax.md b/docs/syntax.md
@@ -85,22 +85,8 @@ tweak:  # optional tweaking of .gv output
   # loops
   loops: <List>  # every list item is itself a list of exactly two pins
                  # on the connector that are to be shorted
-
-  # auto-generation
-  autogenerate: <bool>  # optional; defaults to false; see below
-
 ```
 
-### Auto-generation of connectors
-
-The `autogenerate: true` option is especially useful for very simple, recurring connectors such as crimp ferrules, splices, and others, where it would be a hassle to individually assign unique designators for every instance.
-
-By default, when defining a connector, it will be generated once using the specified designator, and can be referenced multiple times, in different connection sets (see below).
-
-If `autogenerate: true` is set, the connector will _not_ be generated at first. When defining the `connections` section (see below), every time the connector is mentioned, a new instance with an auto-incremented designator is generated and attached.
-
-Since the auto-incremented and auto-assigned designator is not known to the user, one instance of the connector can not be referenced again outside the point of creation. The `autogenerate: true` option is therefore only useful for terminals with only one wire attached, or splices with exactly one wire going in, and one wire going out. If more wires are to be attached (e.g. for a three-way splice, or a crimp where multiple wires are joined), a separate connector with `autogenerate: false` and a user-defined, unique designator needs to be used.
-
 ## Cable attributes
 
 ```yaml
@@ -173,6 +159,7 @@ connections:
   -                # Each list entry is a connection set
     - <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)
@@ -189,16 +176,29 @@ connections:
     - [<connector>, ..., <connector>]     # specify multiple simple connectors to attach in parallel
                                           # these may be unique, auto-generated, or a mix of both
 
+  - # example (arrows between pins)
+    - <connector>: [<pin>, ..., <pin>]
+    - [<arrow>, ..., <arrow>]             # draw arrow linking pins of both connectors
+                                          # use single line arrows (--, <--, <-->, -->)
+    - <connector>: [<pin>, ..., <pin>]
+
+  - # example (arrows between connectors)
+    - <connector>                  
+    - <arrow>                               # draw arrow linking the connectors themselves
+                                            # use double line arrow (==, <==, <==>, ==>)
+    - <connector>
+
   ...    
 ```
 
 - Each connection set is a list of components.
-- The minimum number of items is two.
+- The minimum number of items is one.
 - 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.
+- For `<arrow>`, see below.
 
 ### Single connections
 
@@ -207,7 +207,6 @@ connections:
 - `- <designator>: <int/str>` attaches a pin of the connector, referring to a pin number (from the connector's `pins` attribute) or a pin label (from its `pinlabels` attribute), provided the label is unique.
 
 - `- <designator>` is allowed for simple connectors, since they have only one pin to connect.
-For connectors with `autogenerate: true`, a new instance, with auto-generated designator, is created.
 
 #### Cables
 
@@ -230,14 +229,10 @@ For connectors with `autogenerate: true`, a new instance, with auto-generated de
 - `- [<designator>, ..., <designator>]`
 
   Attaches multiple different single pin connectors, one per connection in the set.
-  For connectors with `autogenerate: true`, a new instance, with auto-generated designator, is created with every mention.
-  Auto-generated and non-autogenerated connectors may be mixed.
 
 - `- <designator>`
 
   Attaches multiple instances of the same single pin connector, one per connectioin in the set.
-  For connectors with `autogenerate: true`, a new instance, with auto-generated designator, is created for every connection in the set.
-  Since only connectors with `pincount: 1` can be auto-generated, pin number 1 is implicit.
 
 #### Cables
 
@@ -249,6 +244,100 @@ For connectors with `autogenerate: true`, a new instance, with auto-generated de
   - `<int>-<int>` auto-expands to a range.
   - `<str>` to refer to a wire's label or color, if unambiguous.
 
+### Arrows
+
+Arrows may be used in place of wires to join two connectors. This can represent the mating of matching connectors.
+
+To represent joining individual pins between two connectors, a list of single arrows is used:
+```yaml
+connections:
+  -
+    - <connector>: [<pin>,...,<pin>]
+    - [<arrow>, ..., <arrow>]         # --, <--, <--> or -->
+    - <connector>: [<pin>,...,<pin>]
+```
+
+To represent mating of two connectors as a whole, one double arrow is used:
+```yaml
+connections:
+  -
+    - <connector>  # using connector designator only
+    - <arrow>      # ==, <==, <==> or ==>
+    - <connector>
+  -
+    - ...
+    - <connector>: [<pin>, ...]  # designator and pinlist (pinlist is ignored)
+                                 # useful when combining arrows and wires
+    - <arrow>                    # ==, <==, <==> or ==>
+    - <connector>: [<pin>, ...]
+    - ...
+```
+
+### Autogeneration of items
+
+If multiple identical copies of a connector or cable are needed, it is possible to define them once as a template, and then generate multiple instances as needed. This is called autogeneration. Both connectors and cables can be autogenerated.
+
+Autogenerated instances of components can be explicitly assigned a designator; this way, they can be referenced in multiple connection sets. However, it is also possible to generate unnamed instances of components. This is especially useful for components that do not need to be referenced in more than one connection set, and where naming each individual instance is an unnecessary complication.
+
+Example (see `connections` section):
+
+```yaml
+connectors:
+  X:
+    # ...
+  Y:
+    # ...
+  Z:
+    style: simple
+    # ...
+cables:
+  V:
+    # ...
+  W:
+    # ...
+
+connections:
+  -  # no autogeneration (normal use)
+    - X: [1,2,...]  # Use X as both the template and the instance designator
+    - V: [1,2,...]  # Use V as both the template and the instance designator
+    # ...
+
+  -  # autogeneration of named instances
+    - Y.Y1: [1,2,...]  # Use template Y, generate instance with designator Y1
+    - W.W1: [1,2,...]  # Use template W, generate instance with designator W1
+    - Y.Y2: [1,2,...]  # generate more instances from the same templates
+    - W.W2: [1,2,...]
+    - Y.Y3: [1,2,...]  
+
+  -  # autogeneration of unnamed instances
+    - Y3:   [1,2,...]  # reuse existing instance Y3
+    - W.W4: [1,2,...]
+    - Z.             # Use template Z, generate one unnamed instance
+                     # for each connection in set
+```
+
+Since the internally assigned designator of an unnamed component is not known to the user, one instance of the connector can not be referenced again outside the point of creation (i.e. in other connection sets, or later in the same set). Autogeneration of unnamed instances is therefore only useful for terminals with only one wire attached, or splices with exactly one wire going in, and one wire going out.
+If a component is to be used in other connection sets (e.g. for a three-way splice, or a crimp where multiple wires are joined), a named instance needs to be used.
+
+Names of autogenerated components are hidden by default. While they can be shown in the graphical output using the `show_name: true` option, it is not recommended to manually use the internally assigned designator (starting with a double underscore `__`), since it might change in future WireViz versions, or when the order of items in connection sets changes.
+
+
+### Unconnected components
+
+Even if a component is not connected to any other components, it must be mentioned in a connection set for it to be displayed.
+
+```yaml
+connectors:
+  X1:  # this connector will not be connected to any other components
+    ... 
+
+connections:
+-
+  - X1  # minimal connection set to include connector in the diagram
+
+```
+
+If any component is defined in the `connectors` or `cables` sections but not referenced in `connections`, a warning is printed in the console.
 
 
 ## Metadata entries
@@ -300,6 +389,7 @@ For connectors with `autogenerate: true`, a new instance, with auto-generated de
   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,
@@ -318,6 +408,7 @@ Parts can be added to a connector or cable in the section `<additional-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

diff --git a/examples/demo01.gv b/examples/demo01.gv