warehack.ing/WireViz
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve documentation

Browse Source 
- Create `docs/` directory
- Add syntax description (`syntax.md`)
- Track changes since first release (`CHANGELOG.md`)
- Expand contribution guidelines (`CONTRIBUTING.md`)
- Improve main readme (`README.md`)
- Add documentation for build script (`buildscript.md`)
This commit is contained in:
Daniel Rojas 2020-07-20 14:14:22 +02:00
parent fb17eae7a6
commit 6db1fcf0fe
8 changed files with 535 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
CHANGELOG.md
View File

@ -1,29 +0,0 @@
# Change Log
## [0.2](https://github.com/formatc1702/WireViz/tree/v0.2) (2020-XX-XX)
### Backward incompatible changes
- Change names of connector attributes ([#77](https://github.com/formatc1702/WireViz/issues/77))
- Remove ferrules as a separate connector type ([#78](https://github.com/formatc1702/WireViz/issues/78))
- Change the way loops are defined ([#79](https://github.com/formatc1702/WireViz/issues/79))
### New features
- Add bidirectional AWG/mm2 conversion ([#41](https://github.com/formatc1702/WireViz/pull/41))
- Add support for part numbers ([#11](https://github.com/formatc1702/WireViz/pull/11))
- Add support for multicolored wires ([#17](https://github.com/formatc1702/WireViz/pull/17), [#96](https://github.com/formatc1702/WireViz/pull/96))
- 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 ([#63](https://github.com/formatc1702/WireViz/issues/63))
- Allow using connector pin names to define connections ([#72](https://github.com/formatc1702/WireViz/issues/72))
- Make defining connection sets easier and more flexible ([#67](https://github.com/formatc1702/WireViz/issues/67))
### Misc. fixes
- Improve BOM generation
- Add various input sanity checks
###
## [0.1](https://github.com/formatc1702/WireViz/tree/v0.1) (2020-06-29)
- Initial release

18
CONTRIBUTING.md
View File

@ -1,18 +0,0 @@
# Contribution Guidelines
When contributing to this repository, please first discuss the change you
wish to make via issue, email, or any other method with the owners of this
repository before making a change.
## Pull Requests
1. Fork this repository to your repository
1. Clone the repository to your local machine
1. Checkout the `dev` branch
1. Make any changes to the code on the `dev` branch
1. Push your changes to your fork
1. Create new pull request
## Documentation Strings
Documentation strings are to follow the Google Style ([examples](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)).

45
docs/CHANGELOG.md Normal file
View File

@ -0,0 +1,45 @@
# Change Log
## [0.2](https://github.com/formatc1702/WireViz/tree/v0.2) (2020-XX-XX)
### 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

43
docs/CONTRIBUTING.md Normal file
View File

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

100
README.md → docs/README.md
View File

@ -1,9 +1,15 @@
# WireViz # 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 ## 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. 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 ## Features
* WireViz input files are fully text based * WireViz input files are fully text based
@ -13,37 +19,26 @@ WireViz is a tool for easily documenting cables, wiring harnesses and connector
* YAML syntax * YAML syntax
* UTF-8 input and output files for special character support * 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, ...) * 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 <!-- * 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 (#158) -->
* Auto-generates standard wire color schemes and allows custom ones if needed * 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/...) * [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/...) * [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/...) * [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/...) * [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 * Understands wire gauge in mm² or AWG
* Optionally auto-calculates equivalent gauge between mm² and AWG * Optionally auto-calculates equivalent gauge between mm² and AWG
* Allows more than one connector per side, as well as loopbacks * Is suitable for both very simple cables, and more complex harnesses.
* Allows for easy-autorouting for 1-to-1 wiring * Allows for easy-autorouting for 1-to-1 wiring
* Generates BOM (Bill of Materials) * 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. _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 <repo url>
cd <working copy>
pip3 install -e .
```
## Examples ## Examples
### Demo 01 ### Demo 01
[WireViz input file](examples/demo01.yml): [WireViz input file](../examples/demo01.yml):
```yaml ```yaml
connectors: connectors:
@ -76,23 +71,56 @@ connections:
Output file: Output file:
![Sample output diagram](examples/demo01.png) ![Sample output diagram](../examples/demo01.png)
[Bill of Materials](examples/demo01.bom.tsv) (auto-generated) [Bill of Materials](../examples/demo01.bom.tsv) (auto-generated)
### Demo 02 ### Demo 02
![](examples/demo02.png) ![](../examples/demo02.png)
[Source](examples/demo02.yml) - [Bill of Materials](examples/demo02.bom.tsv) [Source](../examples/demo02.yml) - [Bill of Materials](../examples/demo02.bom.tsv)
### Tutorial and example gallery ### Tutorial and example gallery
See the [tutorial page](tutorial/readme.md) for sample code, 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. as well as the [example gallery](../examples/readme.md) to see more of what WireViz can do.
## Usage ## 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 <repo url>
cd <working copy>
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 $ wireviz ~/path/to/file/mywire.yml
``` ```
@ -107,29 +135,33 @@ mywire.bom.tsv BOM (bill of materials) as tab-separated text file
mywire.html HTML page with wiring diagram and BOM embedded 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.
### Syntax description
A description of the WireViz YAML input syntax can be found [here](syntax.md).
### (Re-)Building the example projects ### (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: Please see the [documentation](buildscript.md) of the `build_examples.py` script for info on building the demos, examples and tutorial.
```cd src/wireviz
./build_examples.py
```
## Changelog ## Changelog
See [CHANGELOG.md](CHANGELOG.md) See [CHANGELOG.md](CHANGELOG.md)
## Status ## 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. This is very much a work in progress. 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 ## License
[GPL-3.0](LICENSE) [GPL-3.0](../LICENSE)

36
docs/buildscript.md Normal file
View File

@ -0,0 +1,36 @@
# (Re-)Building the example projects
<!--
The following text is taken from #118
https://github.com/formatc1702/WireViz/pull/118
TODO: write a better explaination -->
## 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.

344
docs/syntax.md Normal file
View File

@ -0,0 +1,344 @@
# WireViz Syntax
## Main sections
```yaml
connectors: # dictionary of all used connectors
<str> : # unique connector designator/name
... # connector attributes (see below)
<str> :
...
...
cables: # dictionary of all used cables and wires
<str> : # unique cable designator/name
... # cable attributes (see below)
<str> :
...
...
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> # BOM item (see below)
...
```
## Connector attributes
```yaml
<str> : # unique connector designator/name
# general information about a connector (all optional)
type: <str>
subtype: <str>
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
# 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
# rendering information (all optional)
style: <style> # may be set to simple for single pin connectors
show_name: <bool> # defaults to true for regular connectors,
# false for simple connectors
show_pincount: <bool> # defaults to true for regular connectors
# false for simple connectors
hide_disconnected_pins: <bool> # defaults to false
# 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
<str> : # unique cable designator/name
# general information about a connector (all optional)
category: <category> # may be set to bundle;
# generates one BOM item for every wire in the bundle
# instead of a single item for the entire cable;
# renders with a dashed outline
type: <str>
gauge: <int/float/str> # allowed formats:
# <int/float> mm2 is understood
# <int> AWG is understood
# <int/float> is assumed to be mm2
# <str> custom units and formats are allowed
# 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
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
# conductor information
# the following combinations are permitted:
# wirecount only no color information is specified
# colors only wirecount is inferred from list length
# wirecount + color_code colors are auto-generated based on the specified
# color code (see below) to match the wirecount
# wirecount + colors colors list is trimmed or repeated to match the wirecount
wirecount: <int>
colors: <List> # list of colors (see below)
color_code: <str> # one of the supported cable color codes (see below)
# rendering information (all optional)
show_name: <bool> # defaults to true
show_wirecount: <bool> # defaults to true
```
## Connection sets
A connection set is used to connect multiple components together. Multiple connections can be easily created in parallel within one connection set, by specifying a list of individual pins (for `connectors`) or wires (for `cables`) for every component along the way.
```yaml
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
-...
- # example (single connection)
- <connector>: <pin> # attach one pin of the connector
- <cable>: <wire> # attach one wire of the cable
- <connector> # for simple connectors, pin 1 is implicit
- <cable>: s # for shielded wires, s attaches to the shield
- # example (multiple parallel connections)
- <connector>: [<pin>, ..., <pin> ] # attach multiple pins in parallel
- <cable>: [<wire>, ..., <wire>] # attach multiple wires in parallel
- <connector> # auto-generate a new connector for every parallel connection
- <cable>: [<wire>-<wire>] # specify a range of wires to attach in parallel
- [<connector>, ..., <connector>] # specify multiple simple connectors to attach in parallel
# these may be unique, auto-generated, or a mix of both
...
```
- Each connection set is a list of components.
- The minimum number of items is two.
- 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.
### Single connections
#### Connectors
- `- <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
- `<designator>: <wire>` attaches a specific wire of a cable, using its number.
### Multiple parallel connections
#### Connectors
- `- <designator>: [<pin>, ..., <pin>]`
Each `<pin>` may be:
- `<int/str>` to refer to a specific pin, using its number (from its `pins` attribute) or its label (from its `pinlabels` attribute, provided the label is unique for this connector)
- `<int>-<int>` auto-expands to a range, e.g. `1-4` auto-expands to `1,2,3,4`; `9-7` will auto-expand to `9,8,7`.
- Mixing types is allowed, e.g. `[<pin>, <pinlabel>, <pin>-<pin>, <pin>]`
- `- [<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
- `<designator>: [<wire>, ..., <wire>]`
Each `<wire>` may be:
- `<int>` to refer to a specific wire, using its number.
- `<int>-<int>` auto-expands to a range.
## BOM items
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` (#115) -->
Additional BOM entries can be generated in the sections marked `<bom-item>` above.
<!-- BOM items inside connectors/cables are not implemented yet, but should be soon (#50) -->
```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:
unit: <str>
designators: <List>
pn: <str> # [internal] part number
mpn: <str> # manufacturer part number
manufacturer: <str> # manufacturer name
```
## Colors
Colors are defined via uppercase, two character strings.
Striped/banded wires can be specified by simply concatenating multiple colors, with no space inbetween, eg. `GNYE` for green-yellow.
The following colors are understood:
- `BK` ![##000000](https://via.placeholder.com/15/000000/000000?text=+) (black)
- `WH` ![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=+) (white)
- `GY` ![##999999](https://via.placeholder.com/15/999999/000000?text=+) (grey)
- `PK` ![##ff66cc](https://via.placeholder.com/15/ff66cc/000000?text=+) (pink)
- `RD` ![##ff0000](https://via.placeholder.com/15/ff0000/000000?text=+) (red)
- `OG` ![##ff8000](https://via.placeholder.com/15/ff8000/000000?text=+) (orange)
- `YE` ![##ffff00](https://via.placeholder.com/15/ffff00/000000?text=+) (yellow)
- `OL` ![##708000](https://via.placeholder.com/15/708000/000000?text=+) (olive green)
- `GN` ![##00ff00](https://via.placeholder.com/15/00ff00/000000?text=+) (green)
- `TQ` ![##00ffff](https://via.placeholder.com/15/00ffff/000000?text=+) (turquoise)
- `LB` ![##a0dfff](https://via.placeholder.com/15/a0dfff/000000?text=+) (light blue)
- `BU` ![##0066ff](https://via.placeholder.com/15/0066ff/000000?text=+) (blue)
- `VT` ![##8000ff](https://via.placeholder.com/15/8000ff/000000?text=+) (violet)
- `BN` ![##895956](https://via.placeholder.com/15/895956/000000?text=+) (brown)
- `BG` ![##ceb673](https://via.placeholder.com/15/ceb673/000000?text=+) (beige)
- `IV` ![##f5f0d0](https://via.placeholder.com/15/f5f0d0/000000?text=+) (ivory)
- `SL` ![##708090](https://via.placeholder.com/15/708090/000000?text=+) (slate)
- `CU` ![##d6775e](https://via.placeholder.com/15/d6775e/000000?text=+) (copper)
- `SN` ![##aaaaaa](https://via.placeholder.com/15/aaaaaa/000000?text=+) (tin)
- `SR` ![##84878c](https://via.placeholder.com/15/84878c/000000?text=+) (silver)
- `GD` ![##ffcf80](https://via.placeholder.com/15/ffcf80/000000?text=+) (gold)
<!-- color list generated with a helper script: -->
<!-- https://gist.github.com/formatc1702/3c93fb4c5e392364899283f78672b952 -->
## Cable color codes
Supported color codes:
- `DIN` for [DIN 47100](https://en.wikipedia.org/wiki/DIN_47100)
![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=+) ![##895956](https://via.placeholder.com/15/895956/000000?text=+) ![##00ff00](https://via.placeholder.com/15/00ff00/000000?text=+) ![##ffff00](https://via.placeholder.com/15/ffff00/000000?text=+) ![##999999](https://via.placeholder.com/15/999999/000000?text=+) ![##ff66cc](https://via.placeholder.com/15/ff66cc/000000?text=+) ![##0066ff](https://via.placeholder.com/15/0066ff/000000?text=+) ![##ff0000](https://via.placeholder.com/15/ff0000/000000?text=+) ![##000000](https://via.placeholder.com/15/000000/000000?text=+) ![##8000ff](https://via.placeholder.com/15/8000ff/000000?text=+) ...
- `IEC` for [IEC 60757](https://en.wikipedia.org/wiki/Electronic_color_code#Color_band_system) ("ROY G BIV")
![##895956](https://via.placeholder.com/15/895956/000000?text=+) ![##ff0000](https://via.placeholder.com/15/ff0000/000000?text=+) ![##ff8000](https://via.placeholder.com/15/ff8000/000000?text=+) ![##ffff00](https://via.placeholder.com/15/ffff00/000000?text=+) ![##00ff00](https://via.placeholder.com/15/00ff00/000000?text=+) ![##0066ff](https://via.placeholder.com/15/0066ff/000000?text=+) ![##8000ff](https://via.placeholder.com/15/8000ff/000000?text=+) ![##999999](https://via.placeholder.com/15/999999/000000?text=+) ![##ffffff](https://via.placeholder.com/15/ffffff/000000?text=+) ![##000000](https://via.placeholder.com/15/000000/000000?text=+) ...
- `TEL` and `TELALT` for [25-pair color code](https://en.wikipedia.org/wiki/25-pair_color_code)
- `T568A` and `T568B` for [TIA/EIA-568](https://en.wikipedia.org/wiki/TIA/EIA-568#Wiring) (e.g. Ethernet)
- `BW` for alternating black and white
## Images
Both connectors and cables accept including an image with a caption within their respective nodes.
```yaml
image:
src: <path> # path to the image file
# optional parameters:
caption: <str> # text to display below the image
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.
# if both width and height are specified, the image is stretched to fit.
```
For more fine grained control over the image parameters, please see [`advanced_image_usage.md`](advanced_image_usage.md).
## Multiline strings
The following attributes accept multiline strings:
- `type`
- `subtype` (connectors only)
- `notes`
- `manufacturer`
- `mpn`
- `image.caption`
### Method 1
By using `|`, every following indented line is treated as a new line.
```yaml
attribute: |
This is line 1.
This is line 2.
```
### Method 2
By using double quoted strings, `\n` within the string is converted to a new line.
```yaml
attribute: "This is line 1.\nThis is line 2."
```
Plain (no quotes) or single quoted strings do not convert `\n`.
See [yaml-multiline.info](https://yaml-multiline.info/) for more information.
## Inheritance
[YAML anchors and references](https://blog.daemonl.com/2016/02/yaml.html) are useful for defining and referencing information that is used more than once in a file, e.g. when using defining multiple connectors of the same type or family. See [Demo 02](../examples/demo02.yml) for an example.

2
setup.py
View File

@ -19,7 +19,7 @@ setup(
author='Daniel Rojas', author='Daniel Rojas',
#author_email='', #author_email='',
description='Easily document cables and wiring harnesses', description='Easily document cables and wiring harnesses',
long_description=read(os.path.join(os.path.dirname(__file__), 'README.md')), long_description=read(os.path.join(os.path.dirname(__file__), 'docs/README.md')),
long_description_content_type='text/markdown', long_description_content_type='text/markdown',
install_requires=[ install_requires=[
'pyyaml', 'pyyaml',