From 4c2d8a3795d2a15a168224b2a5919c2950df679b Mon Sep 17 00:00:00 2001 From: Benedikt Werner <1benediktwerner@gmail.com> Date: Sat, 13 Apr 2024 14:05:08 +0200 Subject: [PATCH] Improve wording of documentation (#990) --- CONTRIBUTING.md | 22 ++++++++++---------- DEVELOPMENT.md | 2 +- docs/getting-started/installation.md | 16 +++++++++------ docs/guides/cluster.md | 10 +++++----- docs/guides/diagram.md | 24 +++++++++++----------- docs/guides/edge.md | 6 +++--- docs/guides/node.md | 30 +++++++++++++++------------- scripts/__init__.py | 2 +- templates/apidoc.tmpl | 2 +- 9 files changed, 61 insertions(+), 53 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 90e28a18..d1c430d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,14 +5,14 @@ yourself. ## Set up your environment -* See [DEVELOPMENT][DEVELOPMENT.md] +- See [DEVELOPMENT][DEVELOPMENT.md] ## Resources ### Update nodes -All node classes was auto-generated from image resource files. For example, the -`diagram.aws.compute.EC2` class was auto-generated based on +All node classes are auto-generated from image resource files. For example, the +`diagram.aws.compute.EC2` class is auto-generated based on the `resources/aws/compute/ec2.png` image resource file. So, if you want to add new node resources or update existing node resources, you @@ -30,13 +30,13 @@ ffmpeg -i my_big_image.jpg -vf scale=w=256:h=256:force_original_aspect_ratio=dec Then just run the `./autogen.sh` to generate the added or updated node classes. (cf. [DEVELOPMENT][DEVELOPMENT.md]) -> IMPORTANT NOTE: To run `autogen.sh`, you need [round][round], [black][black] and -> [inkscape][inkscape] command lines that are used for cleaning the image +> IMPORTANT NOTE: To run `autogen.sh`, you need the [round][round], [black][black] and +> [inkscape][inkscape] command line tools that are used for cleaning the image > resource filenames and formatting the generated python code. > -> macOS users can download the inkscape via Homebrew. +> macOS users can download inkscape via Homebrew. > -> Or you should use the docker image. +> Or you can use the docker image. [DEVELOPMENT.md]: ./DEVELOPMENT.md [round]: https://github.com/mingrammer/round @@ -54,11 +54,13 @@ or update the `ALIASES` map in [config.py](config.py). Then just run the `./autogen.sh` to generate the added or updated aliases. (cf. [DEVELOPMENT][DEVELOPMENT.md]) -> IMPORTANT NOTE: To run `autogen.sh`, you need [round][round] and -> [inkscape][inkscape] command lines that are used for cleaning the image +> IMPORTANT NOTE: To run `autogen.sh`, you need the [round][round] and +> [inkscape][inkscape] command line tools that are used for cleaning the image > resource filenames. > -> Or you should use the docker image. +> macOS users can download inkscape via Homebrew. +> +> Or you can use the docker image. ## Run Tests diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 661b8b03..16809070 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -39,7 +39,7 @@ You should have docker installed in your system, if not click [here](https://doc ## 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. 1. Go to diagrams root directory. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 90f6be80..d99f5b0c 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -3,11 +3,13 @@ id: installation title: Installation --- -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 # using pip (pip3) @@ -33,16 +35,18 @@ with Diagram("Web Service", show=False): ELB("lb") >> EC2("web") >> RDS("userdb") ``` -This code generates below diagram. +To generate the diagram, run: ```shell $ python diagram.py ``` +This generates the diagram below: + ![web service diagram](/img/web_service_diagram.png) -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 -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. diff --git a/docs/guides/cluster.md b/docs/guides/cluster.md index f4b55b2d..b24bb446 100644 --- a/docs/guides/cluster.md +++ b/docs/guides/cluster.md @@ -3,13 +3,13 @@ id: cluster title: Clusters --- -Cluster allows you group (or clustering) the nodes in an isolated group. +`Cluster` allows you to group (or cluster) nodes in an isolated group. ## Basic -Cluster represents a local cluster context. +`Cluster` represents a local cluster context. -You can create a cluster context with Cluster class. And you can also connect the nodes in a cluster to other nodes outside a cluster. +You can create a cluster context using the `Cluster` class. You can also connect the nodes in a cluster to other nodes outside a cluster. ```python from diagrams import Cluster, Diagram @@ -33,7 +33,7 @@ with Diagram("Simple Web Service with DB Cluster", show=False): ## Nested Clusters -Nested clustering is also possible. +Nested clustering is also possible: ```python from diagrams import Cluster, Diagram @@ -68,4 +68,4 @@ with Diagram("Event Processing", show=False): ![event processing diagram](/img/event_processing_diagram.png) -> There is no depth limit of nesting. Feel free to create nested clusters as deep as you want. +> There is no depth limit to nesting. Feel free to create nested clusters as deep as you want. diff --git a/docs/guides/diagram.md b/docs/guides/diagram.md index de7f59c0..9d71e98f 100644 --- a/docs/guides/diagram.md +++ b/docs/guides/diagram.md @@ -3,13 +3,13 @@ id: diagram title: Diagrams --- -Diagram is a primary object representing a diagram. +`Diagram` is a primary object representing a diagram. ## 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 from diagrams import Diagram @@ -19,17 +19,17 @@ with Diagram("Simple Diagram"): EC2("web") ``` -And if you run the above script with below command, +If you run the above script with the command below, ```shell $ 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 -Diagrams can be also rendered directly inside the notebook as like this: +Diagrams can also be rendered directly inside Jupyter notebooks like this: ```python from diagrams import Diagram @@ -42,9 +42,9 @@ diag ## 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 from diagrams import Diagram @@ -54,7 +54,7 @@ with Diagram("Simple Diagram", outformat="jpg"): 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 from diagrams import Diagram @@ -64,7 +64,7 @@ with Diagram("Simple Diagram Multi Output", outformat=["jpg", "png", "dot"]): 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 from diagrams import Diagram @@ -74,7 +74,7 @@ with Diagram("Simple Diagram", filename="my_diagram"): 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 from diagrams import Diagram @@ -84,7 +84,7 @@ with Diagram("Simple Diagram", show=False): 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). diff --git a/docs/guides/edge.md b/docs/guides/edge.md index 622ef950..d1e8dfef 100644 --- a/docs/guides/edge.md +++ b/docs/guides/edge.md @@ -3,13 +3,13 @@ id: edge title: Edges --- -Edge is representing an edge between Nodes. +`Edge` represents an edge between nodes. ## Basic -Edge is an object representing a connection between Nodes with some additional properties. +`Edge` is an object representing a connection between nodes with some additional properties. -An edge object contains three attributes: **label**, **color** and **style** which mirror corresponding graphviz edge attributes. +An edge object contains three attributes: **label**, **color**, and **style**. They mirror the corresponding Graphviz edge attributes. ```python from diagrams import Cluster, Diagram, Edge diff --git a/docs/guides/node.md b/docs/guides/node.md index f0f524a7..462440a1 100644 --- a/docs/guides/node.md +++ b/docs/guides/node.md @@ -3,11 +3,11 @@ id: node title: Nodes --- -Node is a second object representing a node or system component. +`Node` is an object representing a node or system component. ## Basic -Node is an abstract concept that represents a single system component object. +`Node` is an abstract concept that represents a single system component object. A node object consists of three parts: **provider**, **resource type** and **name**. You may already have seen each part in the previous example. @@ -19,9 +19,9 @@ with Diagram("Simple Diagram"): EC2("web") ``` -In above example, the `EC2` is a node of `compute` resource type which provided by `aws` provider. +In the example above, the `EC2` is a node of resource type `compute` which is provided by the `aws` provider. -You can use other node objects in a similar manner like: +You can use other node objects in a similar manner: ```python # aws resources @@ -42,7 +42,7 @@ from diagrams.alibabacloud.storage import ObjectTableStore # gcp resources from diagrams.gcp.compute import AppEngine, GKE -from diagrams.gcp.ml import AutoML +from diagrams.gcp.ml import AutoML ... # k8s resources @@ -57,15 +57,17 @@ from diagrams.oci.network import Firewall from diagrams.oci.storage import FileStorage, StorageGateway ``` -You can find all available nodes list in [Here](https://diagrams.mingrammer.com/docs/nodes/aws). +You can find lists of all available nodes for each provider in the sidebar on the left. + +For example, [here](https://diagrams.mingrammer.com/docs/nodes/aws) is the list of all available AWS nodes. ## Data Flow -You can represent data flow by connecting the nodes with these operators: `>>`, `<<` and `-`. +You can represent data flow by connecting the nodes with the operators `>>`, `<<`, and `-`. -* **>>**: Connect nodes in left to right direction. -* **<<**: Connect nodes in right to left direction. -* **-**: Connect nodes in no direction. Undirected. +- **>>** connects nodes in left to right direction. +- **<<** connects nodes in right to left direction. +- **-** connects nodes in no direction. Undirected. ```python from diagrams import Diagram @@ -80,15 +82,15 @@ with Diagram("Web Services", show=False): (ELB("lb") >> EC2("web")) - EC2("web") >> RDS("userdb") ``` -> 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. ![web services diagram](/img/web_services_diagram.png) > 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 from diagrams import Diagram @@ -110,7 +112,7 @@ with Diagram("Workers", show=False, direction="TB"): ## 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: ```python from diagrams import Diagram diff --git a/scripts/__init__.py b/scripts/__init__.py index 81d31281..5f7fbe72 100644 --- a/scripts/__init__.py +++ b/scripts/__init__.py @@ -4,7 +4,7 @@ from pathlib import Path import config as cfg -def base_dir() -> str: +def base_dir() -> Path: return Path(os.path.abspath(os.path.dirname(__file__))).parent diff --git a/templates/apidoc.tmpl b/templates/apidoc.tmpl index f5fc3233..75af3cfb 100644 --- a/templates/apidoc.tmpl +++ b/templates/apidoc.tmpl @@ -3,7 +3,7 @@ id: {{ pvd }} title: {{ pvd|up_or_title(pvd) }} --- -Node classes list of {{ pvd }} provider. +Node classes list of the {{ pvd }} provider. {% for typ, classes in typ_classes.items() %} ## {{ pvd }}.{{ typ }} {% for class in classes %}