Skip to content

Commit

Permalink
Merge branch 'dev'
Browse files Browse the repository at this point in the history
  • Loading branch information
@formatc1702
formatc1702 committed Oct 11, 2021
2 parents bdc405a + eb7be15 commit be1ecd4
Show file tree
Hide file tree
Showing 121 changed files with 11,052 additions and 8,993 deletions.
2 changes: 1 addition & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,4 @@ dist
venv/
desktop.ini
thumbs.db

temp/
31 changes: 31 additions & 0 deletions docs/CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,35 @@
# Change Log

## [0.3](https://github.com/formatc1702/WireViz/tree/v0.3) (2021-10-11)

### 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))
- 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)

### Backward incompatible changes
Expand All @@ -16,6 +46,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))
Expand Down
1 change: 1 addition & 0 deletions docs/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ When contributing to this repository, please [submit a new issue](https://github
1. Commit your code changes to this feature branch.
1. Push the changes to your fork.
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.

### Hints
Expand Down
194 changes: 167 additions & 27 deletions docs/syntax.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,17 @@ additional_bom_items: # custom items to add to BOM
- <bom-item> # BOM item (see below)
...

```
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)
...

tweak: # optional tweaking of .gv output
...
```
## Connector attributes
```yaml
Expand All @@ -43,17 +52,29 @@ 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
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)

# 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)
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
Expand Down Expand Up @@ -98,19 +119,28 @@ 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)
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
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)

# conductor information
# the following combinations are permitted:
Expand All @@ -123,9 +153,14 @@ 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
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

```

Expand Down Expand Up @@ -162,6 +197,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

Expand Down Expand Up @@ -210,34 +247,130 @@ 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

Connectors (both regular, and auto-generated), cables, and wires of a bundle are automatically added to the BOM.
## Metadata entries

<!-- unless the `ignore_in_bom` attribute is set to `true` (#115) -->
```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
```
Additional BOM entries can be generated in the sections marked `<bom-item>` above.
## BOM items and additional components
<!-- BOM items inside connectors/cables are not implemented yet, but should be soon (#50) -->
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.

Parts can be added to a connector or cable in the section `<additional-component>` which will also list them in the graph.

```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
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.

```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
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
Expand Down Expand Up @@ -272,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:
Expand All @@ -298,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.
Expand All @@ -315,7 +452,10 @@ The following attributes accept multiline strings:
- `notes`
- `manufacturer`
- `mpn`
- `supplier`
- `spn`
- `image.caption`
- `tweak.append`

### Method 1

Expand Down
8 changes: 4 additions & 4 deletions examples/demo01.bom.tsv
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit be1ecd4

Please sign in to comment.