Make handling of unconnected components more explicit

docs/CHANGELOG.md

@@ -4,14 +4,17 @@
 
 ### Backward-incompatible changes
 - New syntax for autogenerated components ([#184](https://github.com/wireviz/WireViz/issues/184), [#186](https://github.com/wireviz/WireViz/pull/186))
-- New command line interface ([#244](https://github.com/wireviz/WireViz/pull/244))
+  - 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.
 
 
 ### 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))
 
 
 ### Misc. fixes

docs/syntax.md

@@ -192,7 +192,7 @@ connections:
 ```
 
 - 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.
@@ -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
 
@@ -280,7 +275,9 @@ connections:
 
 ### Autogeneration of items
 
-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, autogeneration may be used. Both connectors and cables can be autogenerated.
+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):
 
@@ -325,6 +322,24 @@ If a component is to be used in other connection sets (e.g. for a three-way spli
 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
 
 ```yaml

src/wireviz/wireviz.py

@@ -355,6 +355,19 @@ def alternate_type():  # flip between connector and cable/arrow
                         # mate two connectors as a whole
                         harness.add_mate_component(from_name, to_name, designator)
 
+    # warn about unused templates
+
+    proposed_components = list(template_connectors.keys()) + list(
+        template_cables.keys()
+    )
+    used_components = set(designators_and_templates.values())
+    forgotten_components = [c for c in proposed_components if not c in used_components]
+    if len(forgotten_components) > 0:
+        print(
+            "Warning: The following components are not referenced in any connection set:"
+        )
+        print(", ".join(forgotten_components))
+
     # harness population completed =============================================
 
     if "additional_bom_items" in yaml_data: