Merge branch 'refactor/big-refactor-squashed' into dev-refactored

.gitattributes

@@ -2,8 +2,8 @@ docs/* linguist-documentation
 examples/* linguist-documentation
 tutorial/* linguist-documentation
 
-**/*.bom.tsv linguist-generated
-**/*.bom.csv linguist-generated
+**/*.tsv linguist-generated
+**/*.csv linguist-generated
 **/*.gv linguist-generated
 **/*.html linguist-generated
 **/*.png linguist-generated

.github/workflows/main.yml

@@ -4,29 +4,39 @@ on: [push, pull_request, workflow_dispatch]
 
 jobs:
   build:
-    runs-on: ubuntu-latest
     strategy:
-      max-parallel: 4
+      max-parallel: 6
       matrix:
-        python-version: [3.7, 3.8]
+        # ubuntu-22.04 supports Python 3.7-3.12
+        # ubuntu-24.04 (currently latest & preferred) supports Python 3.9-3.12
+        # More details: https://github.com/actions/runner-images/issues/10636
+        os: [ubuntu-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        include:
+          - os: ubuntu-22.04
+            python-version: "3.7"
+          - os: ubuntu-22.04
+            python-version: "3.8"
+    runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Setup Graphviz
-      uses: ts-graphviz/setup-graphviz@v1
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install .
-    - name: Create Examples
-      run: PYTHONPATH=$(pwd)/src:$PYTHONPATH cd src/wireviz/ && python build_examples.py
-    - name: Upload examples, demos, and tutorials
-      uses: actions/upload-artifact@v2
-      with:
-        name: examples-and-tutorials
-        path: |
-          examples/
-          tutorial/
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Setup Graphviz
+        uses: ts-graphviz/setup-graphviz@v2
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+      - name: Create Examples
+        run: PYTHONPATH=$(pwd)/src/wireviz:$PYTHONPATH cd src/wireviz/tools/ && python build_examples.py
+      - name: Upload examples, demos, and tutorials
+        uses: actions/upload-artifact@v4
+        with:
+          name: examples-and-tutorials-v${{ matrix.python-version }}
+          path: |
+            examples/
+            tutorial/
+          if-no-files-found: error

.gitignore

@@ -1,15 +1,21 @@
+# OS-specific files
 .DS_Store
+desktop.ini
+Thumbs.db
+
+# Development aids
 .idea/
-.eggs
-__pycache__
-.*.swp
-*.egg-info
-*.pyc
-build
-data
-dist
+.vscode/
+temp/
 venv/
 .venv/
-desktop.ini
-thumbs.db
-temp/
+
+# Build/compile/release artifacts
+build/
+dist/
+*.egg-info
+*.pyc
+
+# Other temporary files
+__pycache__
+.*.swp

cleanup.sh

@@ -0,0 +1,5 @@
+#!/bin/zsh
+
+autoflake -i --remove-all-unused-imports src/wireviz/*.py
+isort src/wireviz/*py
+black src/wireviz/*.py

devtools.txt

@@ -0,0 +1,12 @@
+# The following tools have proven useful during development
+# Feel free to install while inside the WireViz virtualenv, using:
+# pip install -r devtools.txt
+
+# Code formatting
+black  # black src/wireviz/*.py
+isort  # isort src/wireviz/*py
+
+# Development aids
+pudb       # import pudb; pudb.set_trace()
+autoflake  # autoflake -i --remove-all-unused-imports src/wireviz/*.py
+pyan       # pyan3 src/wireviz/*.py -uncge --html > temp/pyan.html

docs/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contribution Guidelines
 
-When contributing to this repository, please [submit a new issue](https://github.com/formatc1702/WireViz/issues) first to discuss the proposed change, before submitting a pull request.
+When contributing to this repository, please [submit a new issue](https://github.com/wireviz/WireViz/issues) first to discuss the proposed change, before submitting a pull request.
 
 ## Submitting a new Issue
 
@@ -27,7 +27,7 @@ When contributing to this repository, please [submit a new issue](https://github
 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.
+  - If your code changes or extends the WireViz YAML syntax, be sure to update the [syntax description document](https://github.com/wireviz/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.
 
 ### Hints

docs/README.md

@@ -74,13 +74,13 @@ Output file:
 
 ![Sample output diagram](../examples/demo01.png)
 
-[Bill of Materials](../examples/demo01.bom.tsv) (auto-generated)
+[Bill of Materials](../examples/demo01.tsv) (auto-generated)
 
 ### Demo 02
 
 ![](../examples/demo02.png)
 
-[Source](../examples/demo02.yml) - [Bill of Materials](../examples/demo02.bom.tsv)
+[Source](../examples/demo02.yml) - [Bill of Materials](../examples/demo02.tsv)
 
 ### Syntax, tutorial and example gallery
 
@@ -133,11 +133,11 @@ Depending on the options specified, this will output some or all of the followin
 mywire.gv         GraphViz output
 mywire.svg        Wiring diagram as vector image
 mywire.png        Wiring diagram as raster image
-mywire.bom.tsv    BOM (bill of materials) as tab-separated text file
+mywire.tsv        BOM (bill of materials) as tab-separated text file
 mywire.html       HTML page with wiring diagram and BOM embedded
 ```
 
-Wildcars in the file path are also supported to process multiple files at once, e.g.:
+Wildcards in the file path are also supported to process multiple files at once, e.g.:
 ```
 $ wireviz ~/path/to/files/*.yml
 ```

docs/buildscript.md

@@ -2,7 +2,7 @@
 
 <!--
 The following text is taken from #118
-https://github.com/formatc1702/WireViz/pull/118
+https://github.com/wireviz/WireViz/pull/118
 
 TODO: write a better explaination -->
 
@@ -26,7 +26,7 @@ Possible group names:
   - `tutorial` to process`tutorial/{readme.md,tutorial*.*}`
   - `demos` to process`examples/demo*.*`
 
-  Affected filetypes: `.gv`, `.bom.tsv`, `.png`, `.svg`, `.html`
+  Affected filetypes: `.gv`, `.tsv`, `.png`, `.svg`, `.html`
 
 
 ## Usage hints

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):
 
@@ -322,9 +319,29 @@ connections:
 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.
 
+The default character to trigger autogeneration of components is `.`. A different character can be specified using the `template_separator` option (see below).
+
 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
@@ -338,6 +355,7 @@ Names of autogenerated components are hidden by default. While they can be shown
   # If no value is specified for 'title', then the
   # output filename without extension is used.
 ```
+See [HTML Output Templates](../src/wireviz/templates/) for how metadata entries can be inserted into the HTML output.
 
 ## Options
 
@@ -372,6 +390,9 @@ Names of autogenerated components are hidden by default. While they can be shown
   # 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
+
+  # Character to split template and designator for autogenerated components
+  template_separator: <str>    # Default = '.'
 ```
 
 
@@ -393,6 +414,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
@@ -478,7 +500,7 @@ The following colors are understood:
 - `GD` ![##ffcf80](https://via.placeholder.com/15/ffcf80/000000?text=+) (gold)
 
 <!-- color list generated with a helper script: -->
-<!-- https://gist.github.com/formatc1702/3c93fb4c5e392364899283f78672b952 -->
+<!-- https://gist.github.com/17o2/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.