From c9cc94d6806b225bbf57f1e25cc381828e0c178e Mon Sep 17 00:00:00 2001 From: Daniel Rojas Date: Mon, 20 Jul 2020 14:14:22 +0200 Subject: [PATCH] Improve documentation - 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`) --- CHANGELOG.md | 29 --- CONTRIBUTING.md | 18 -- docs/CHANGELOG.md | 45 +++++ docs/CONTRIBUTING.md | 43 +++++ README.md => docs/README.md | 98 ++++++---- docs/buildscript.md | 36 ++++ docs/syntax.md | 344 ++++++++++++++++++++++++++++++++++++ setup.py | 2 +- 8 files changed, 534 insertions(+), 81 deletions(-) delete mode 100644 CHANGELOG.md delete mode 100644 CONTRIBUTING.md create mode 100644 docs/CHANGELOG.md create mode 100644 docs/CONTRIBUTING.md rename README.md => docs/README.md (50%) create mode 100644 docs/buildscript.md create mode 100644 docs/syntax.md diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 5192789a..00000000 --- a/CHANGELOG.md +++ /dev/null @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 7a94ac7e..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -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)). diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 00000000..d97a40c9 --- /dev/null +++ b/docs/CHANGELOG.md @@ -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)) +- 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/README.md b/docs/README.md similarity index 50% rename from README.md rename to docs/README.md index e973b634..ad2e4aa3 100644 --- a/README.md +++ b/docs/README.md @@ -1,9 +1,15 @@ # 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 @@ -13,37 +19,26 @@ WireViz is a tool for easily documenting cables, wiring harnesses and connector * 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, ...) - * 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/...) + * [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 -* 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 * 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): +[WireViz input file](../examples/demo01.yml): ```yaml connectors: @@ -76,23 +71,56 @@ connections: 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 -![](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 -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. +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 ``` @@ -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 ``` -### (Re-)Building the example projects +#### Command line options -If you would like to rebuild all of the included demos, examples and tutorials, use the ```build_examples.py``` script: +- `--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. -```cd src/wireviz -./build_examples.py -``` +### 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](https://github.com/formatc1702/WireViz/projects/1). Source code, API, syntax and functionality may change wildly at any time. - -## Requirements +## Status -Developed and tested using Python 3.7; might not work with older Python versions. +This is very much a work in progress. Source code, API, syntax and functionality may change wildly at any time. -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 -[GPL-3.0](LICENSE) +[GPL-3.0](../LICENSE) 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: