graph cmd docs

docs/cmd/graph.md

@@ -0,0 +1,99 @@
+# graph command
+
+### Description
+
+The `graph` command generates graphical representaitons of the deployed topology.
+
+Two graphing options are available:
+
+* an HTML page with embedded graphics generated by `containerlab` based on a Go HTML template
+* a [graph description file in dot format](https://en.wikipedia.org/wiki/DOT_(graph_description_language)) that can be rendered using [Graphviz](https://graphviz.org/) or viewed [online](https://dreampuf.github.io/GraphvizOnline/).
+
+#### HTML
+
+The HTML based graph is created by rendering a [Go HTML](https://golang.org/pkg/html/template/) template against a `struct` containing the topology name as well as a `json` string where 2 lists are present: `nodes` and `links` .
+
+`nodes` contains data about the lab nodes, such as name, kind, type, image, state, IP addresses,...
+
+`links` contains the list of links defined by source node and target node, as well as the endpoint names
+
+```json
+{
+  "nodes": [
+    {
+      "name": "node1-1",
+      "image": "srlinux:20.6.1-286",
+      "kind": "srl",
+      "group": "tier-1",
+      "state": "running/Up 21 seconds",
+      "ipv4_address": "172.23.23.3/24",
+      "ipv6_address": "2001:172:23:23::3/80"
+    },
+    // omitted rest of nodes
+  ],
+  "links": [
+    {
+      "source": "node1-2",
+      "source_endpoint": "e1-1",
+      "target": "node2-1",
+      "target_endpoint": "e1-2"
+    },
+    {
+      "source": "node2-1",
+      "source_endpoint": "e1-4",
+      "target": "node3-1",
+      "target_endpoint": "e1-1"
+    },
+    // omitted rest of links 
+  ]
+}
+```
+
+Within the template, Javascript libraries such as [**d3js directed force graph**](https://observablehq.com/collection/@d3/d3-force) or [**vis.js network**](https://visjs.github.io/vis-network/docs/network/) can be used to generate custom topology graphs.
+
+`containerlab` comes with a (minimalistic) default template using [d3js](https://github.com/d3/d3-force).
+
+After the graph generation, it's possible to move the nodes to a desired position and export the graph in PNG format.
+
+![default_graph](https://gitlab.com/rdodin/pics/-/wikis/uploads/5f3ade3559a5f044d4786bfd0e278b65/image.png)
+
+#### Graphviz
+
+When `graph` command is called without the `--srv` flag, containerlab will generate a [graph description file in dot format](https://en.wikipedia.org/wiki/DOT_(graph_description_language)).
+
+The dot file can be used to view the graphical representation of the topology either by rendering the dot file into a PNG file or using [online dot viewer](https://dreampuf.github.io/GraphvizOnline/).
+
+### Usage
+
+`containerlab [global-flags] graph [local-flags]`
+
+### Flags
+
+#### name
+
+With the global `--name | -n` flag a user sets the name of the lab that will be graphed.
+
+#### srv
+
+The `--srv` flag enables the HTML graph representation if present, it specifies an address a HTTP server will listen to.
+
+A single path `/` is served, where the graph is generated based on either a default template or on the template supplied using `--template`.
+
+#### template
+
+The `--template` flag allows to customize the HTML based graph by supplying a user defined template that will be rendered and exposed on the address specified by `--srv`.
+
+
+### Examples
+
+```bash
+
+# generate a graph description file in dot format for topo1 topology
+containerlab graph --topo /path/to/topo1.yaml
+
+# start an http server on :3002 where topo1 graph will be rendered using the default template
+containerlab graph --topo /path/to/topo1.yaml --srv ":3002"
+
+# start an http server on :3002 where topo1 graph will be rendered using a custom template my_template.html
+containerlab graph --topo /path/to/topo1.yaml --srv ":3002" --template my_template.html
+```

mkdocs.yml

@@ -14,6 +14,7 @@ nav:
           - inspect: cmd/inspect.md
           - save: cmd/save.md
           - generate: cmd/generate.md
+          - graph: cmd/graph.md
   - Lab examples:
       - About: lab-examples/lab-examples.md
       - Single SR Linux node: lab-examples/single-srl.md