From f3b78c22fe39a6cad81f2d5c8032e1190f9ac13a Mon Sep 17 00:00:00 2001
From: chrizzftd <chris.gfz@gmail.com>
Date: Sat, 22 Feb 2020 11:16:36 +1100
Subject: [PATCH] graphviz on docs (#16)

---
 README.md                | 31 +++++++++++++++++-----
 docs/source/Overview.rst | 20 ++++++---------
 docs/source/example.dot  | 55 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 87 insertions(+), 19 deletions(-)
 create mode 100644 docs/source/example.dot

diff --git a/README.md b/README.md
index 130ee98..9b07ba7 100644
--- a/README.md
+++ b/README.md
@@ -7,12 +7,8 @@
 
 Object-oriented names for the digital era.
 
-naming provides a simple yet flexible and scalable interface for naming conventions.
-It follows the UNIX tradition of single-purpose tools that do one thing well.
-
-<div class="footer">
-        <img src="https://docs.google.com/drawings/d/1wU-T04kgE7O_uVr4XRNIxGsnZP-TJmVxG5mqQE6mMNM/pub?w=1380&amp;h=980">
-    </div>
+`naming` provides an interface for dealing with naming conventions; from
+defining them, to identifying names and creating new ones.
     
 ### Installation
 
@@ -24,4 +20,25 @@ $ pip install naming
 
 ### Usage
 
-Refer to the [documentation](http://naming.readthedocs.io/en/latest/) for details on contents and usage.
+Please refer to the [documentation](http://naming.readthedocs.io/en/latest/) for details on contents and usage.
+
+```python
+>>> import naming
+>>> class NameFileConvention(naming.Name, naming.File):
+...     config = dict(first=r'\w+', last=r'\w+', number=r'\d+')
+...
+>>> name = NameFileConvention('john doe 07.jpg')
+>>> name.last
+'doe'
+>>> name.number
+'07'
+>>> name.get_name(first='jane', number=99)
+'jane doe 99.jpg'
+>>> name.last = 'connor'
+>>> name
+NameFileConvention("john connor 07.jpg")
+>>> name.number = 'not_a_number'
+...
+ValueError: Can't set invalid name 'john connor not_a_number.jpg' on NameFileConvention instance. Valid convention is: '{first} {last} {number}.{suffix}' with pattern: ^(?P<first>\w+)\ (?P<last>\w+)\ (?P<number>\d+)(\.(?P<suffix>\w+))$'
+```
+
diff --git a/docs/source/Overview.rst b/docs/source/Overview.rst
index 115b643..c6a66b2 100644
--- a/docs/source/Overview.rst
+++ b/docs/source/Overview.rst
@@ -3,20 +3,17 @@ Overview
 
 .. topic:: Name Objects
 
-    This package offers classes representing names as strings that follow a certain pattern convention. New Name
-    objects can subclass from the provided classes in a simple manner. Each Name object has a **config** attribute
+    This package offers classes representing names as strings that follow a certain pattern convention.
+    Each Name object has a **config** attribute
     that contains the fields and regex patterns of the convention to follow. Names can also drop fields from their
     parent classes with the **drop** attribute, or they can merge / split fields with the **join** attribute.
 
-Class Flow
-==========
+Composition Example
+===================
+.. graphviz:: example.dot
 
-.. raw:: html
-
-    <img src="https://docs.google.com/drawings/d/1wU-T04kgE7O_uVr4XRNIxGsnZP-TJmVxG5mqQE6mMNM/pub?w=690&amp;h=490">
-
-Basic Use
-=========
+Usage
+=====
 
 .. topic:: Built-ins & `config` attribute
 
@@ -127,8 +124,7 @@ Basic Use
 
 .. topic:: Extending Names
 
-    The **config**, **drop** and **join** attributes are merged on the subclasses to provide a simple but flexible
-    and scalable system that can help rule all names in a project.
+    The **config**, **drop** and **join** attributes are merged on subclasses.
 
     Inheriting from an existing name::
 
diff --git a/docs/source/example.dot b/docs/source/example.dot
new file mode 100644
index 0000000..08ff942
--- /dev/null
+++ b/docs/source/example.dot
@@ -0,0 +1,55 @@
+strict digraph G {
+    // nodes creation, shape and style defined here
+    bgcolor=invis
+    {
+      node [style="rounded, filled" shape=box]
+      class, FILE, PIPE, PIPEFILE
+    }
+    {
+      node [style=filled margin=0 width=1 height=0.46 shape=polygon fixedsize=true skew=0.4]
+      format, file_format, pipe_format, pipefile_format
+    }
+    {
+      node [shape=none]
+      patterns, file_patterns, pipe_patterns, pipefile_patterns
+    }
+    {
+      node [style="dashed, filled" shape=box]
+      example, file_example, pipe_example, pipefile_example
+    }
+    // connections, labels and color related updates by higher level groups
+    subgraph legend {
+        edge[style=invis]  // connect with invisible edges to emulate a legend
+        class, format, example, patterns [color=gray40 fillcolor=gray95]
+        patterns [label="field=pattern" fontcolor=gray22]
+        class -> format -> patterns  -> example
+    }
+
+    FILE, file_format, file_example [color=lightgoldenrod3 fillcolor=lemonchiffon1]
+    file_format [label=".{suffix}"]
+    file_example [label=".ext"]
+    // escape the inverse slash so generated image displays one
+    file_patterns [label="suffix = \\w+" fontcolor=lightgoldenrod4]
+
+    PIPE, pipe_format, pipe_example [color=lightskyblue4 fillcolor=lightblue]
+    pipe_format [label=".{pipe}"]
+    pipe_example [label=".1
+    .1.out
+    .1.out.101"]
+    pipe_patterns [label="version = \\d+
+    output = \\w+?
+    frame = \\d+?"]
+
+    PIPEFILE, pipefile_format, pipefile_example [color=mediumorchid4 fillcolor=plum2]
+    pipefile_format [skew=0.15 width=2 label="{base}.{pipe}.{suffix}"]
+    pipefile_example [label="wip_data.7.ext
+    pipe_data.7.out.ext
+    framed_data.7.out.101.ext"]
+    pipefile_patterns [label="base = \\w+" fontcolor=mediumorchid4]
+
+    edge [color=gray36 arrowhead="vee"]
+    PIPE -> pipe_format -> pipe_patterns -> pipe_example
+    FILE -> file_format -> file_patterns -> file_example
+    PIPEFILE -> pipefile_format -> pipefile_patterns -> pipefile_example
+    {PIPE, FILE} -> PIPEFILE
+}