@ -39,7 +39,7 @@ You should have docker installed in your system, if not click [here](https://doc
## Mac local development setup
## Mac local development setup
To be able to develop and run diagrams locally on you Mac device, you should have [Python](https://www.python.org/downloads/), [Go](https://golang.org/doc/install) and [brew](https://brew.sh/) installed on your system.
To be able to develop and run diagrams locally on you Mac device, you should have [Python](https://www.python.org/downloads/), [Go](https://golang.org/doc/install), and [brew](https://brew.sh/) installed on your system.
It requires **Python 3.6** or higher, check your Python version first.
**diagrams** requires **Python 3.6** or higher, check your Python version first.
It uses [Graphviz](https://www.graphviz.org/) to render the diagram, so you need to [install Graphviz](https://graphviz.gitlab.io/download/) to use **diagrams**. After installing graphviz (or already have it), install the **diagrams**.
**diagrams** uses [Graphviz](https://www.graphviz.org/) to render the diagram, so you need to [install Graphviz](https://graphviz.gitlab.io/download/) to use it.
> macOS users can download the Graphviz via `brew install graphviz` if you're using [Homebrew](https://brew.sh). Similarly, Windows users with [Chocolatey](https://chocolatey.org) installed can run `choco install graphviz`.
> macOS users using [Homebrew](https://brew.sh) can install Graphviz via `brew install graphviz` . Similarly, Windows users with [Chocolatey](https://chocolatey.org) installed can run `choco install graphviz`.
After installing Graphviz (or if you already have it), install **diagrams**:
```shell
```shell
# using pip (pip3)
# using pip (pip3)
@ -33,16 +35,18 @@ with Diagram("Web Service", show=False):
ELB("lb") >> EC2("web") >> RDS("userdb")
ELB("lb") >> EC2("web") >> RDS("userdb")
```
```
This code generates below diagram.
To generate the diagram, run:
```shell
```shell
$ python diagram.py
$ python diagram.py
```
```
This generates the diagram below:
It will be saved as `web_service.png`on your working directory.
It will be saved as `web_service.png`in your working directory.
## Next
## Next
See more [Examples](/docs/getting-started/examples) or see [Guides](/docs/guides/diagram) page for more details.
See more [Examples](/docs/getting-started/examples) or see the [Guides](/docs/guides/diagram) page for more details.
Diagram is a primary object representing a diagram.
`Diagram` is a primary object representing a diagram.
## Basic
## Basic
Diagram represents a global diagram context.
`Diagram` represents a global diagram context.
You can create a diagram context with Diagram class. The first parameter of Diagram constructor will be used for output filename.
You can create a diagram context with the `Diagram` class. The first parameter of the `Diagram` constructor will be used to generate the output filename.
```python
```python
from diagrams import Diagram
from diagrams import Diagram
@ -19,17 +19,17 @@ with Diagram("Simple Diagram"):
EC2("web")
EC2("web")
```
```
And if you run the above script with below command,
If you run the above script with the command below,
```shell
```shell
$ python diagram.py
$ python diagram.py
```
```
It will generate an image file with single `EC2` node drawn as `simple_diagram.png` on your working directory, and open that created image file immediately.
it will generate an image file with single `EC2` node drawn as `simple_diagram.png` in your working directory and open that created image file immediately.
## Jupyter Notebooks
## Jupyter Notebooks
Diagrams can be also rendered directly inside the notebook as like this:
Diagrams can also be rendered directly inside Jupyter notebooks like this:
```python
```python
from diagrams import Diagram
from diagrams import Diagram
@ -42,9 +42,9 @@ diag
## Options
## Options
You can specify the output file format with `outformat` parameter. Default is **png**.
You can specify the output file format with the `outformat` parameter. The default is **png**.
> (png, jpg, svg, pdf and dot) are allowed.
> Allowed formats are: png, jpg, svg, pdf, and dot
```python
```python
from diagrams import Diagram
from diagrams import Diagram
@ -54,7 +54,7 @@ with Diagram("Simple Diagram", outformat="jpg"):
EC2("web")
EC2("web")
```
```
The `outformat` parameter also support list to output all the defined output in one call.
The `outformat` parameter also supports a list to output all the defined outputs in one call:
```python
```python
from diagrams import Diagram
from diagrams import Diagram
@ -64,7 +64,7 @@ with Diagram("Simple Diagram Multi Output", outformat=["jpg", "png", "dot"]):
EC2("web")
EC2("web")
```
```
You can specify the output filename with `filename` parameter. The extension shouldn't be included, it's determined by the `outformat` parameter.
You can specify the output filename with the `filename` parameter. The extension shouldn't be included, it's determined by the `outformat` parameter.
```python
```python
from diagrams import Diagram
from diagrams import Diagram
@ -74,7 +74,7 @@ with Diagram("Simple Diagram", filename="my_diagram"):
EC2("web")
EC2("web")
```
```
You can also disable the automatic file opening by setting the `show` parameter as **false**. Default is **true**.
You can also disable the automatic file opening by setting the `show` parameter to **false**. The default is **true**.
```python
```python
from diagrams import Diagram
from diagrams import Diagram
@ -84,7 +84,7 @@ with Diagram("Simple Diagram", show=False):
EC2("web")
EC2("web")
```
```
It allows custom Graphviz dot attributes options.
Diagrams also allow custom Graphviz dot attributes options.
> `graph_attr`, `node_attr` and `edge_attr` are supported. Here is a [reference link](https://www.graphviz.org/doc/info/attrs.html).
> `graph_attr`, `node_attr` and `edge_attr` are supported. Here is a [reference link](https://www.graphviz.org/doc/info/attrs.html).
> Be careful when using the `-` and any shift operators together, which could cause unexpected results due to operator precedence.
> Be careful when using `-` and any shift operators together. It can cause unexpected results due to Python's operator precedence, so you might have to use parentheses.
> The order of rendered diagrams is the reverse of the declaration order.
> The order of rendered diagrams is the reverse of the declaration order.
You can change the data flow direction with `direction` parameter. Default is **LR**.
You can change the data flow direction with the `direction` parameter. The default is **LR**.
> (TB, BT, LR and RL) are allowed.
> Allowed values are: TB, BT, LR, and RL
```python
```python
from diagrams import Diagram
from diagrams import Diagram
@ -110,7 +112,7 @@ with Diagram("Workers", show=False, direction="TB"):
## Group Data Flow
## Group Data Flow
Above worker example has too many redundant flows. In this case, you can group nodes into a list so that all nodes are connected to other nodes at once.
The above worker example has too many redundant flows. To avoid this, you can group nodes into a list so that all nodes are connected to other nodes at once:
Benedikt Werner
7 months ago
committed by
GitHub