docs: update

.markdownlint.yaml

@@ -0,0 +1,3 @@
+default: true
+MD025:
+  front_matter_title: ""

.vscode/settings.json

@@ -19,11 +19,16 @@
     "Esep",
     "Functors",
     "Rects",
+    "Serializable",
     "Stringn",
+    "Styleable",
     "Tpng",
     "edgehref",
     "ediamond",
     "emicklei",
+    "emicklei's",
+    "fontawesome",
+    "graphviz",
     "headhref",
     "icurve",
     "labelhref",
@@ -35,7 +40,9 @@
     "mosek",
     "nojustify",
     "nslimit",
+    "pymdownx",
     "sortv",
+    "superfences",
     "tailhref",
     "voro",
     "xdot",

Node.go

@@ -7,6 +7,7 @@ type Node interface {
 	attributes.Identity
 	attributes.Styleable
 	attributes.Serializable
+
 	// Edge creates an Edge to a Node
 	Edge(to Node) Edge
 	// EdgeWithAttributes creates an Edge with the provided attributes to a Node

README.md

@@ -81,9 +81,9 @@ import (
 func main() {
   graph := dot.NewGraph()
   graph.SetAttributeString("label", "an amazing graph")
-  clusterA := graph.Subgraph(&GraphOptions{ ID: "Cluster A", Cluster: true })
+  clusterA := graph.Subgraph(WithID("Cluster A"), WithCluster())
   clusterA.SetAttributeString("label", "Cluster A")
-  clusterB := graph.Subgraph(&GraphOptions{ ID: "Cluster B", Cluster: true })
+  clusterB := graph.Subgraph(WithID("Cluster B"), WithCluster())
   clusterB.SetAttributeString("label", "Cluster B")
 
   clusterA.
@@ -99,24 +99,49 @@ func main() {
 }
 ```
 
-The attributes sub-package has all supported keys defined as variables, and can
+The constants sub-package has all supported keys defined as variables, and can
 be used instead of plain strings to avoid both duplication and errors:
 
 ```go
-graph := dot.NewGraph()
-graph.SetAttributeString(attributes.KeyLabel, "a graph")
-node := graph.Node("n1")
-node.SetAttributeString(attributes.KeyLabel, "a node")
-edge := graph.Edge(graph.Node("n2"), graph.Node("n3"))
-edge.SetAttributeString(attributes.KeyLabel, "a edge")
+package main
+
+import (
+  "os"
+  "github.com/wwmoraes/dot"
+  "github.com/wwmoraes/dot/constants"
+)
+
+func main() {
+  graph := dot.NewGraph()
+  graph.SetAttributeString(constants.KeyLabel, "a graph")
+  node := graph.Node("n1")
+  node.SetAttributeString(constants.KeyLabel, "a node")
+  edge := graph.Edge(graph.Node("n2"), graph.Node("n3"))
+  edge.SetAttributeString(constants.KeyLabel, "a edge")
+
+  fd, _ := os.Create("sample.dot")
+  graph.WriteTo(fd)
+}
 ```
 
 You can also set literals and HTML values using the helper functions:
 
 ```go
-graph := dot.NewGraph()
-graph.Node("n1").SetAttributeLiteral(attributes.KeyLabel, `a left label\l`)
-graph.Node("n2").SetAttributeHTML(attributes.KeyLabel, `<b>a bold label</b>`)
+package main
+
+import (
+  "os"
+  "github.com/wwmoraes/dot"
+  "github.com/wwmoraes/dot/constants"
+)
+
+func main() {
+  graph := dot.NewGraph()
+  graph.Node("n1").SetAttributeLiteral(constants.KeyLabel, `a left label\l`)
+  graph.Node("n2").SetAttributeHTML(constants.KeyLabel, `<b>a bold label</b>`)
+  fd, _ := os.Create("sample.dot")
+  graph.WriteTo(fd)
+}
 ```
 
 ## ✍️ Authors <a name = "authors"></a>

docs/attributes/interfaces/Identity.md

@@ -0,0 +1,14 @@
+---
+title: Identity
+description: implemented by values that have an immutable identifier
+---
+
+# `Identity`
+
+Implemented by values that have an immutable identifier
+
+## source
+
+```go
+--8<-- "attributes/Identity.go"
+```

docs/attributes/interfaces/Reader.md

@@ -0,0 +1,14 @@
+---
+title: Reader
+description: implemented by attribute-based values that allows reading them
+---
+
+# `Reader`
+
+Implemented by attribute-based values that allows reading them
+
+## source
+
+```go
+--8<-- "attributes/Reader.go"
+```

docs/attributes/interfaces/Serializable.md

@@ -0,0 +1,15 @@
+---
+title: Serializable
+description: implemented by values that can be printed as string or written directly into an IO device
+---
+
+# `Serializable`
+
+Implemented by values that can be printed as string or written directly into an
+IO device.
+
+## source
+
+```go
+--8<-- "attributes/Serializable.go"
+```

docs/attributes/interfaces/Styleable.md

@@ -0,0 +1,14 @@
+---
+title: Styleable
+description: implemented by values that support attributes
+---
+
+# `Styleable`
+
+Implemented by values that support attributes
+
+## source
+
+```go
+--8<-- "attributes/Styleable.go"
+```

docs/attributes/interfaces/Writer.md

@@ -0,0 +1,14 @@
+---
+title: Writer
+description: implemented by attribute-based values that allows mutating them
+---
+
+# `Writer`
+
+Implemented by attribute-based values that allows mutating them
+
+## source
+
+```go
+--8<-- "attributes/Writer.go"
+```

docs/constants/Key.md

@@ -0,0 +1,15 @@
+---
+title: Key
+description: attribute key values
+---
+
+# `Key`
+
+All Graphviz known attributes are mapped as `string` constants to prevent typos
+and the creation of multiple string literals across the code.
+
+## source
+
+```go
+--8<-- "constants/Key.go"
+```

docs/index.md

@@ -4,7 +4,7 @@
     this package is a WIP and will introduce breaking changes while on major
     version zero.
 
-[![Status](https://img.shields.io/badge/status-active-success.svg)]()
+[![Status](https://img.shields.io/badge/status-active-success.svg)](https://github.com/wwmoraes/dot)
 ![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/wwmoraes/dot)
 [![Go Report Card](https://goreportcard.com/badge/github.com/wwmoraes/dot)](https://goreportcard.com/report/github.com/wwmoraes/dot)
 [![GoDoc](https://godoc.org/github.com/wwmoraes/dot?status.svg)](https://pkg.go.dev/github.com/wwmoraes/dot)
@@ -19,7 +19,7 @@ implementation focused on generating dot/gv files that [Graphviz](graphviz) can
 then convert into any of its output formats supported (e.g. png, jpeg, svg, pdf).
 
 Dot provides both interfaces and ready-to-use concrete types that represent
-[dot language](dotlanguage) resources - namely Graphs, Nodes and Edges, plus all
+[dot language](dot-language) resources - namely Graphs, Nodes and Edges, plus all
 attributes.
 
 This package was inspired/initially forked from [emicklei/dot](emicklei-dot),
@@ -51,10 +51,13 @@ func main() {
 
   graph.Node("n1").SetAttributeString("label", "hello dot!")
 
-  graph.Write(os.Create("sample.dot"))
+  fd, _ := os.Create("sample.dot")
+  defer fd.Close()
+
+  graph.WriteTo(fd)
 }
 ```
 
 [graphviz]: https://graphviz.org
-[dotlanguage]: http://www.graphviz.org/doc/info/lang.html
+[dot-language]: http://www.graphviz.org/doc/info/lang.html
 [emicklei-dot]: https://github.com/emicklei/dot

docs/interfaces/StyledEdge.md

@@ -0,0 +1,14 @@
+---
+title: StyledEdge
+description: implemented by edge values with convenience styling methods
+---
+
+# `StyledEdge`
+
+Implemented by dot-compatible edge values which have convenience styling methods
+
+## source
+
+```go
+--8<-- "StyledEdge.go"
+```

docs/interfaces/edge.md

@@ -1,7 +1,14 @@
-# Edge
+---
+title: Edge
+description: implemented by dot-compatible edge values
+---
+
+# `Edge`
 
 Implemented by dot-compatible edge values, with support for attributes.
 
+## source
+
 ```go
 --8<-- "Edge.go"
 ```

docs/interfaces/graph.md

@@ -1,6 +1,16 @@
-# Graph
+---
+title: Graph
+description: implemented by dot-compatible graph values
+---
+
+# `Graph`
 
 Implemented by dot-compatible graph values, with support for attributes.
+Extends attributes' [Identity](../attributes/interfaces/Identity.md),
+[Styleable](../attributes/interfaces/Styleable.md) and
+[Serializable](../attributes/interfaces/Serializable.md) interfaces.
+
+## source
 
 ```go
 --8<-- "Graph.go"

docs/interfaces/node.md

@@ -1,7 +1,14 @@
-# Node
+---
+title: Node
+description: implemented by dot-compatible node values
+---
+
+# `Node`
 
 Implemented by dot-compatible node values, with support for attributes.
 
+## source
+
 ```go
 --8<-- "Node.go"
 ```

docs/types/GraphOptionFn.md

@@ -0,0 +1,50 @@
+---
+title: GraphOptionFn
+description: functor that mutates graph options
+---
+
+# `GraphOptionFn`
+
+Implemented by functor values that set properties on a `GraphOptions` instance,
+which are then used by `Graph`s `NewGraph`/`Graph.Subgraph` to configure new
+[sub]graphs.
+
+A `nil` error is expected as a return value if the functor has successfully set
+the options it is intended to.
+
+These functors are usually returned by `With*` functions that are free to accept
+any parameters to be used within the functor, e.g.
+
+```go
+func WithMyOptions(id string) GraphOptionFn {
+  return func(options GraphOptions) error {
+    // use the given id
+    options.SetID(id)
+    // always create as strict
+    options.SetStrict(true)
+    // use undirected (graph) instead of the default directed (digraph)
+    options.SetType(GraphTypeUndirected)
+
+    return nil
+  }
+}
+```
+
+then it can be used as
+
+```go
+graph, _ := dot.NewGraph(WithMyOptions("some-id"))
+```
+
+## implementation
+
+```go
+// GraphOptionFn is a functor that mutates graph options
+type GraphOptionFn func(GraphOptions) error
+```
+
+## source
+
+```go
+--8<-- "Graph.go"
+```

mkdocs.yml

@@ -14,6 +14,7 @@ theme:
   - navigation.instant
   - navigation.tabs
 markdown_extensions:
+- meta
 - admonition
 - pymdownx.tabbed
 - pymdownx.superfences