Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature/update readme #133

Merged
merged 1 commit into from
Aug 1, 2020
Merged

Feature/update readme #133

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 41 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
# 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
Expand All @@ -26,17 +28,6 @@ WireViz is a tool for easily documenting cables, wiring harnesses and connector

_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

Expand Down Expand Up @@ -90,8 +81,39 @@ Output file:
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 <repo url>
cd <working copy>
git checkout dev
pip3 install -e .
Comment on lines +109 to +112
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please make sure this workflow makes sense.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should you also mention something like the alternative variant you gave to me in #43 (comment)?

git clone https://github.com/formatc1702/WireViz.git
cd WireViz/
python -m venv wv-env
source wv-env/bin/activate
pip3 install -e .
cd src/wireviz
python build_examples.py

Note that git checkout dev is missing above, and I have not tried any of these installations from scratch recently.

Copy link
Collaborator

@kvid kvid Jul 29, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should there be a link to CONTRIBUTING.md near the end of the section about Installing the development version?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, didn't see these comments earlier.

  • I'm not sure whether we should give advice on virtual environments directly, or reference a site that explains the concept more generally.
  • Sure, I can include a link to CONTRIBUTING.md

```

### How to run

```
$ wireviz ~/path/to/file/mywire.yml
```
Expand All @@ -106,28 +128,28 @@ mywire.bom.tsv BOM (bill of materials) as tab-separated text file
mywire.html HTML page with wiring diagram and BOM embedded
```

### Syntax description

A description of the WireViz YAML input syntax can be found [here](syntax.md).


### (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:
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

```

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

Expand Down