diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..deb5a71c --- /dev/null +++ b/.gitattributes @@ -0,0 +1,10 @@ +docs/* linguist-documentation +examples/* linguist-documentation +tutorial/* linguist-documentation + +**/*.bom.tsv linguist-generated +**/*.bom.csv linguist-generated +**/*.gv linguist-generated +**/*.html linguist-generated +**/*.png linguist-generated +**/*.svg linguist-generated diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index ec26b95b..301ac18a 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -1,6 +1,6 @@ name: Create Examples -on: [push, pull_request] +on: [push, pull_request, workflow_dispatch] jobs: build: @@ -22,4 +22,11 @@ jobs: python -m pip install --upgrade pip pip install . - name: Create Examples - run: PYTHONPATH=$(pwd)/src:$PYTHONPATH cd src/wireviz/ && python build_examples.py \ No newline at end of file + 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/ \ No newline at end of file diff --git a/.gitignore b/.gitignore index cc614ada..67144ab1 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,6 @@ build data dist venv/ +desktop.ini +thumbs.db + diff --git a/README.md b/README.md deleted file mode 100644 index b96dd42c..00000000 --- a/README.md +++ /dev/null @@ -1,126 +0,0 @@ -# WireViz - -## Summary - -WireViz is a tool for easily documenting cables, wiring harnesses and connector pinouts. It takes plain text, YAML-formatted files as input and produces beautiful graphical output (SVG, PNG, ...) thanks to [GraphViz](https://www.graphviz.org/). It handles automatic BOM (Bill of Materials) creation and has a lot of extra features. - -## Features - -* WireViz input files are fully text based - * No special editor required - * Human readable - * Easy version control - * YAML syntax -* Understands and uses color abbreviations as per [IEC 60757](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system) (black=BK, red=RD, ...) - * Optionally outputs colors as abbreviation (e.g. 'YE'), full name (e.g. 'yellow') or hex value (e.g. '#ffff00'), with choice of UPPER or lower case -* Auto-generates standard wire color schemes and allows custom ones if needed - * [DIN 47100](https://en.wikipedia.org/wiki/DIN_47100) (WT/BN/GN/YE/GY/PK/BU/RD/BK/VT/...) - * [IEC 62](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system) (BN/RD/OR/YE/GN/BU/VT/GY/WT/BK/...) -* Understands wire gauge in mm² or AWG - * Optionally auto-calculates equivalent gauge between mm² and AWG -* Allows more than one connector per side, as well as loopbacks -* Allows for easy-autorouting for 1-to-1 wiring -* Generates BOM (Bill of Materials) - -_Note_: WireViz is not designed to represent the complete wiring of a system. Its main aim is to document the construction of individual wires and harnesses. - -## Installation - -WireWiz requires GraphViz to be installed in order to work. See the [GraphViz download page](https://graphviz.org/download/) for OS-specific instructions. - -Installation of the WireWiz package and its Python dependencies can be done using pip after cloning the repository: - -``` -git clone -cd -pip3 install -e . -``` - -## Examples - -### Demo 01 - -[WireViz input file](examples/demo01.yml): - -```yaml -connectors: - X1: - type: D-Sub - subtype: female - pinout: [DCD, RX, TX, DTR, GND, DSR, RTS, CTS, RI] - X2: - type: Molex KK 254 - subtype: female - pinout: [GND, RX, TX] - -cables: - W1: - gauge: 0.25 mm2 - length: 0.2 - color_code: DIN - wirecount: 3 - shield: true - -connections: - - - - X1: [5,2,3] - - W1: [1,2,3] - - X2: [1,3,2] - - - - X1: 5 - - W1: s -``` - -Output file: - -![Sample output diagram](examples/demo01.png) - -[Bill of Materials](examples/demo01.bom.tsv) (auto-generated) - -### Demo 02 - -![](examples/demo02.png) - -[Source](examples/demo02.yml) - [Bill of Materials](examples/demo02.bom.tsv) - -### 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. - -## Usage - -``` -$ wireviz ~/path/to/file/mywire.yml -``` - -This will output the following files - -``` -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.html HTML page with wiring diagram and BOM embedded -``` - -### (Re-)Building the example projects - -If you would like to rebuild all of the included demos, examples and tutorials, use the ```build_examples.py``` script: - -```cd src/wireviz -./build_examples.py -``` -## Status - -This is very much a [work in progress](https://github.com/formatc1702/WireViz/projects/1). Source code, API, syntax and functionality may change wildly at any time. - -## Requirements - -Developed and tested using Python 3.7; might not work with older Python versions. - -Ubuntu 18.04 LTS users in particular may need to separately install Python 3.7 or above, as that comes with Python 3.6 as the included system Python install. - -## License - -GNU GPLv3 diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 00000000..9f043a28 --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,45 @@ +# Change Log + +## [0.2](https://github.com/formatc1702/WireViz/tree/v0.2) (2020-10-17) + +### Backward incompatible changes + +- Change names of connector attributes ([#77](https://github.com/formatc1702/WireViz/issues/77), [#105](https://github.com/formatc1702/WireViz/pull/105)) + - `pinnumbers` is now `pins` + - `pinout` is now `pinlabels` +- Remove ferrules as a separate connector type ([#78](https://github.com/formatc1702/WireViz/issues/78), [#102](https://github.com/formatc1702/WireViz/pull/102)) + - Simple connectors like ferrules are now defined using the `style: simple` attribute +- Change the way loops are defined ([#79](https://github.com/formatc1702/WireViz/issues/79), [#75](https://github.com/formatc1702/WireViz/pull/75)) + - Wires looping between two pins of the same connector are now handled via the connector's `loops` attribute. + +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)) +- Add support for images ([#27](https://github.com/formatc1702/WireViz/issues/27), [#153](https://github.com/formatc1702/WireViz/pull/153)) +- Add ability to export data directly to other programs ([#55](https://github.com/formatc1702/WireViz/pull/55)) +- Add support for line breaks in various fields ([#49](https://github.com/formatc1702/WireViz/issues/49), [#64](https://github.com/formatc1702/WireViz/pull/64)) +- Allow using connector pin names to define connections ([#72](https://github.com/formatc1702/WireViz/issues/72), [#139](https://github.com/formatc1702/WireViz/issues/139), [#140](https://github.com/formatc1702/WireViz/pull/140)) +- Make defining connection sets easier and more flexible ([#67](https://github.com/formatc1702/WireViz/issues/67), [#75](https://github.com/formatc1702/WireViz/pull/75)) +- Add new command line options ([#167](https://github.com/formatc1702/WireViz/issues/167), [#173](https://github.com/formatc1702/WireViz/pull/173)) +- Add new features to `build_examples.py` ([#118](https://github.com/formatc1702/WireViz/pull/118)) +- Add new colors ([#103](https://github.com/formatc1702/WireViz/pull/103), [#113](https://github.com/formatc1702/WireViz/pull/113), [#144](https://github.com/formatc1702/WireViz/issues/144), [#145](https://github.com/formatc1702/WireViz/pull/145)) +- Improve documentation ([#107](https://github.com/formatc1702/WireViz/issues/107), [#111](https://github.com/formatc1702/WireViz/pull/111)) + + +### Misc. fixes + +- Improve BOM generation +- Add various input sanity checks +- Improve HTML output ([#66](https://github.com/formatc1702/WireViz/issues/66), [#136](https://github.com/formatc1702/WireViz/pull/136), [#95](https://github.com/formatc1702/WireViz/pull/95), [#177](https://github.com/formatc1702/WireViz/pull/177)) +- Fix node rendering bug ([#69](https://github.com/formatc1702/WireViz/issues/69), [#104](https://github.com/formatc1702/WireViz/pull/104)) +- Improve shield rendering ([#125](https://github.com/formatc1702/WireViz/issues/125), [#126](https://github.com/formatc1702/WireViz/pull/126)) +- Add GitHub Linguist overrides ([#146](https://github.com/formatc1702/WireViz/issues/146), [#154](https://github.com/formatc1702/WireViz/pull/154)) + + +## [0.1](https://github.com/formatc1702/WireViz/tree/v0.1) (2020-06-29) + +- Initial release diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000..b11c0696 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,43 @@ +# 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. + +## Submitting a new Issue + +- First, search existing (open and closed) issues for any related issues. + - You might then find an existing answer or suggested solution to your issue, possibly also an existing PR you can test. + - When finding existing issues that seem related to your issue, please include references (# followed by issue number) to related issues in your new issue description, or if a very similar issue is still open, consider adding a comment in that issue instead of creating a new one. +- When appropriate, please prefix your issue title with one of these category prefixes followed by a space: + - **[bug]** When the issue seems to be caused by a bug. + - **[feature]** When requesting a feature change or new feature. + - **[internal]** When suggesting code improvements that doesn't change any output. + - **[doc]** For documentation issues. + - **[meta]** For issues about the development or contribution process. +- Please include enough information in the description to enable another user to reproduce any error state described in your issue: + - The versions of your WireViz, Graphviz (`dot -V`), Python (`python -V`), and operating system. + - The relevant input files unless (preferably) you can demonstrate the same issue using one of the example files. If your input file is large or complex, please try to find a smaller/simplified input that still can reproduce the same issue. + - Any warnings or error messages you get. +- See also [How We Write Github Issues](https://wiredcraft.com/blog/how-we-write-our-github-issues/) in general. + +## Submitting a new Pull Request + +1. Fork this repository and clone it on your local machine. +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. Submit a new pull request, using `dev` as the base branch. +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 + +- Make sure to [write good commit messages](https://chris.beams.io/posts/git-commit/). +- Always consider `git rebase` before `git merge` when joining commits from different branches, to keep the commit history simple and easier to read. +- If the `dev` branch has advanced since your fork, consider rebasing onto the current state to avoid merge conflicts. +- Avoid committing changes to generated files in PRs (examples, tutorials, etc.) to reduce merging conflicts. The owner will rebuild them. +- For complex PRs, consider [interactively rebasing](https://thoughtbot.com/blog/git-interactive-rebase-squash-amend-rewriting-history) your contribution to remove intermediate commits and clean up the commit history. +- Feel free to submit a [draft PR](https://github.blog/2019-02-14-introducing-draft-pull-requests/) for your work-in-progress. This lets other contributors comment on and review your code, while clearly marking it as not ready for merging. + + +## Documentation Strings + +Documentation strings are to follow the Google Style ([examples](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..ad2e4aa3 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,167 @@ +# WireViz + + +[![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/) + +## Summary + +WireViz is a tool for easily documenting cables, wiring harnesses and connector pinouts. It takes plain text, YAML-formatted files as input and produces beautiful graphical output (SVG, PNG, ...) thanks to [GraphViz](https://www.graphviz.org/). It handles automatic BOM (Bill of Materials) creation and has a lot of extra features. + + +## Features + +* WireViz input files are fully text based + * No special editor required + * Human readable + * Easy version control + * YAML syntax + * UTF-8 input and output files for special character support +* Understands and uses color abbreviations as per [IEC 60757](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system) (black=BK, red=RD, ...) + +* Auto-generates standard wire color schemes and allows custom ones if needed + * [DIN 47100](https://en.wikipedia.org/wiki/DIN_47100) (WT/BN/GN/YE/GY/PK/BU/RD/BK/VT/...) + * [IEC 60757](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system) (BN/RD/OR/YE/GN/BU/VT/GY/WT/BK/...) + * [25 Pair Color Code](https://en.wikipedia.org/wiki/25-pair_color_code#Color_coding) (BUWH/WHBU/OGWH/WHOG/GNWH/WHGN/BNWH/...) + * [TIA/EIA 568 A/B](https://en.wikipedia.org/wiki/TIA/EIA-568#Wiring) (Subset of 25-Pair, used in CAT-5/6/...) +* Understands wire gauge in mm² or AWG + * Optionally auto-calculates equivalent gauge between mm² and AWG +* Is suitable for both very simple cables, and more complex harnesses. +* Allows for easy-autorouting for 1-to-1 wiring +* Generates BOM (Bill of Materials) + +_Note_: WireViz is not designed to represent the complete wiring of a system. Its main aim is to document the construction of individual wires and harnesses. + + +## Examples + +### Demo 01 + +[WireViz input file](../examples/demo01.yml): + +```yaml +connectors: + X1: + type: D-Sub + subtype: female + pinlabels: [DCD, RX, TX, DTR, GND, DSR, RTS, CTS, RI] + X2: + type: Molex KK 254 + subtype: female + pinlabels: [GND, RX, TX] + +cables: + W1: + gauge: 0.25 mm2 + length: 0.2 + color_code: DIN + wirecount: 3 + shield: true + +connections: + - + - X1: [5,2,3] + - W1: [1,2,3] + - X2: [1,3,2] + - + - X1: 5 + - W1: s +``` + +Output file: + +![Sample output diagram](../examples/demo01.png) + +[Bill of Materials](../examples/demo01.bom.tsv) (auto-generated) + +### Demo 02 + +![](../examples/demo02.png) + +[Source](../examples/demo02.yml) - [Bill of Materials](../examples/demo02.bom.tsv) + +### 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. + + +## Usage + +### Installation + +#### Requirements + +WireViz requires Python 3.7 or later. + +WireWiz requires GraphViz to be installed in order to work. See the [GraphViz download page](https://graphviz.org/download/) for OS-specific instructions. + +_Note_: Ubuntu 18.04 LTS users in particular may need to separately install Python 3.7 or above, as that comes with Python 3.6 as the included system Python install. + +#### Installing the latest release + +The latest WireViz release can be downloaded from [PyPI](https://pypi.org/project/wireviz/) with the following command: +``` +pip3 install wireviz +``` + +#### Installing the development version + +Access to the current state of the development branch can be gained by cloning the repo and installing manually: + +``` +git clone +cd +git checkout dev +pip3 install -e . +``` + +If you would like to contribute to this project, make sure you read the [contribution guidelines](CONTRIBUTING.md)! + +### How to run + +``` +$ wireviz ~/path/to/file/mywire.yml +``` + +This will output the following files + +``` +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.html HTML page with wiring diagram and BOM embedded +``` + +#### Command line options + +- `--prepend-file ` to prepend an additional YAML file. Useful for part libraries and templates shared among multiple cables/harnesses. +- `-o ` or `--output_file ` 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. + + +### Syntax description + +A description of the WireViz YAML input syntax can be found [here](syntax.md). + + +### (Re-)Building the example projects + +Please see the [documentation](buildscript.md) of the `build_examples.py` script for info on building the demos, examples and tutorial. + +## Changelog + +See [CHANGELOG.md](CHANGELOG.md) + + +## Status + +This is very much a work in progress. Source code, API, syntax and functionality may change wildly at any time. + + +## License + +[GPL-3.0](../LICENSE) diff --git a/docs/advanced_image_usage.md b/docs/advanced_image_usage.md new file mode 100644 index 00000000..5fd4288f --- /dev/null +++ b/docs/advanced_image_usage.md @@ -0,0 +1,61 @@ +# Advanced Image Usage + +In rare cases when the [ordinary image scaling functionality](syntax.md#images) is insufficient, a couple of extra optional image attributes can be set to offer extra image cell space and scaling functionality when combined with the image dimension attributes `width` and `height`, but in most cases their default values below are sufficient: +- `scale: ` (how an image will use the available cell space) is default `false` if no dimension is set, or `true` if only one dimension is set, or `both` if both dimensions are set. +- `fixedsize: ` (scale to fixed size or expand to minimum size) is default `false` when no dimension is set or if a `scale` value is set, and `true` otherwise. +- When `fixedsize` is true and only one dimension is set, then the other dimension is calculated using the image aspect ratio. If reading the aspect ratio fails, then 1:1 ratio is assumed. + +See explanations of all supported values for these attributes in subsections below. + +## The effect of `fixedsize` boolean values + +- When `false`, any `width` or `height` values are _minimum_ values used to expand the image cell size for more available space, but cell contents or other size demands in the table might expand this cell even more than specified by `width` or `height`. +- When `true`, both `width` and `height` values are required by Graphwiz and specify the fixed size of the image cell, distorting any image inside if it don't fit. Any borders are normally drawn around the fixed size, and therefore, WireViz enclose the image cell in an extra table without borders when `fixedsize` is true to keep the borders around the outer non-fixed cell. + +## The effect of `scale` string values: + +- When `false`, the image is not scaled. +- When `true`, the image is scaled proportionally to fit within the available image cell space. +- When `width`, the image width is expanded (height is normally unchanged) to fill the available image cell space width. +- When `height`, the image height is expanded (width is normally unchanged) to fill the available image cell space height. +- When `both`, both image width and height are expanded independently to fill the available image cell space. + +In all cases (except `true`) the image might get distorted when a specified fixed image cell size limits the available space to less than what an unscaled image needs. + +In the WireViz diagrams there are no other space demanding cells in the same row, and hence, there are never extra available image cell space height unless a greater image cell `height` also is set. + +## Usage examples + +All examples of `image` attribute combinations below also require the mandatory `src` attribute to be set. + +- Expand the image proportionally to fit within a minimum height and the node width: +```yaml + height: 100 # Expand image cell to this minimum height + fixedsize: false # Avoid scaling to a fixed size + # scale default value is true in this case +``` + +- Increase the space around the image by expanding the image cell space (width and/or height) to a larger value without scaling the image: +```yaml + width: 200 # Expand image cell to this minimum width + height: 100 # Expand image cell to this minimum height + scale: false # Avoid scaling the image + # fixedsize default value is false in this case +``` + +- Stretch the image width to fill the available space in the node: +```yaml + scale: width # Expand image width to fill the available image cell space + # fixedsize default value is false in this case +``` + +- Stretch the image height to a minimum value: +```yaml + height: 100 # Expand image cell to this minimum height + scale: height # Expand image height to fill the available image cell space + # fixedsize default value is false in this case +``` + +## How Graphviz support this image scaling + +The connector and cable nodes are rendered using a HTML `` containing an image cell `
` with `width`, `height`, and `fixedsize` attributes containing an image `` with `src` and `scale` attributes. See also the [Graphviz doc](https://graphviz.org/doc/info/shapes.html#html), but note that WireViz uses default values as described above. diff --git a/docs/buildscript.md b/docs/buildscript.md new file mode 100644 index 00000000..2655770e --- /dev/null +++ b/docs/buildscript.md @@ -0,0 +1,36 @@ +# (Re-)Building the example projects + + + +## Commands + +- `python build_examples.py` to build generated files in all groups. +- `python build_examples.py compare` to compare generated files in all groups against the last commit. +- `python build_examples.py clean` to delete generated files in all groups. +- `python build_examples.py restore` to restore generated files in all groups from the last commit. +- `python build_examples.py -V` or `--version` to display the WireViz version. +- `python build_examples.py -h` or `--help` to see a summary of the usage help text. + + +## Options + +- Append `-b` or `--branch` followed by a specified branch or commit to compare with or restore from (default: The last commit in the current branch). +- Append `-c` or `--compare-graphviz-output` to the `compare` command above to also compare the Graphviz output (default: False). +- Append `-g` or `--groups` followed by space separated group names to any command above, and the set of generated files affected by the command will be limited to the selected groups. +Possible group names: + - `examples` to process `examples/{readme.md,ex*.*}` + - `tutorial` to process`tutorial/{readme.md,tutorial*.*}` + - `demos` to process`examples/demo*.*` + + Affected filetypes: `.gv`, `.bom.tsv`, `.png`, `.svg`, `.html` + + +## Usage hints + +- Run `python build_examples.py` after any code changes to verify that it still is possible to process YAML-input from all groups without errors. +- Run `python build_examples.py compare` after the rebuilding above to verify that the output differences are as expected after a code change. +- Run `python build_examples.py restore` before adding and committing to avoid including changes to generated files after the rebuilding above. diff --git a/docs/syntax.md b/docs/syntax.md new file mode 100644 index 00000000..a0a30c27 --- /dev/null +++ b/docs/syntax.md @@ -0,0 +1,344 @@ +# WireViz Syntax + +## Main sections + +```yaml +connectors: # dictionary of all used connectors + : # unique connector designator/name + ... # connector attributes (see below) + : + ... + ... + +cables: # dictionary of all used cables and wires + : # unique cable designator/name + ... # cable attributes (see below) + : + ... + ... + +connections: # list of all connections to be made + # between cables and connectors + - + ... # connection set (see below) + - + ... + ... + +additional_bom_items: # custom items to add to BOM + - # BOM item (see below) + ... + +``` + +## Connector attributes + +```yaml + : # unique connector designator/name + # general information about a connector (all optional) + type: + subtype: + color: # see below + image: # see below + notes: + + # product information (all optional) + pn: # [internal] part number + mpn: # manufacturer part number + manufacturer: # manufacturer name + + # pinout information + # at least one of the following must be specified + pincount: # if omitted, is set to length of specified list(s) + pins: # if omitted, is autofilled with [1, 2, ..., pincount] + pinlabels: # if omitted, is autofilled with blanks + + # rendering information (all optional) + style: