Mermaid-based Example State Diagrams (#3090)

Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>

AUTHORS.rst

@@ -29,6 +29,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Balduro <https://github.com/Balduro>`_
 - `Bibo-Joshi <https://github.com/Bibo-Joshi>`_
 - `bimmlerd <https://github.com/bimmlerd>`_
+- `cyc8 <https://github.com/cyc8>`_ 
 - `d-qoi <https://github.com/d-qoi>`_
 - `daimajia <https://github.com/daimajia>`_
 - `Daniel Reed <https://github.com/nmlorg>`_

docs/requirements-docs.txt

@@ -1,4 +1,5 @@
 sphinx==5.0.1
 sphinx-pypi-upload
 furo==2022.6.4.1
-sphinx-paramlinks==0.5.4
+sphinx-paramlinks==0.5.4
+sphinxcontrib-mermaid==0.7.1

docs/source/_static/style_mermaid_diagrams.css

@@ -0,0 +1,3 @@
+.mermaid svg {
+  height: auto;
+}

docs/source/conf.py

@@ -45,6 +45,7 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.linkcode",
     "sphinx_paramlinks",
+    "sphinxcontrib.mermaid",
 ]
 
 # Use intersphinx to reference the python builtin library docs
@@ -211,7 +212,10 @@ html_favicon = "ptb-logo_1024.ico"
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-html_css_files = ["style_external_link.css"]
+html_css_files = [
+    "style_external_link.css",
+    "style_mermaid_diagrams.css",
+]
 html_permalinks_icon = "¶"  # Furo's default permalink icon is `#`` which doesn't look great imo.
 
 # Output file base name for HTML help builder.

docs/source/examples.conversationbot.rst

@@ -10,5 +10,4 @@
 State Diagram
 -------------
 
-.. image:: ../../examples/conversationbot.png
-    
+.. mermaid:: ../../examples/conversationbot.mmd

docs/source/examples.conversationbot2.rst

@@ -10,5 +10,4 @@
 State Diagram
 -------------
 
-.. image:: ../../examples/conversationbot2.png
-    
+.. mermaid:: ../../examples/conversationbot2.mmd

docs/source/examples.nestedconversationbot.rst

@@ -10,5 +10,4 @@
 State Diagram
 -------------
 
-.. image:: ../../examples/nestedconversationbot.png
-    
+.. mermaid:: ../../examples/nestedconversationbot.mmd

examples/conversationbot.mmd

@@ -0,0 +1,21 @@
+flowchart TB
+    %% Documentation: https://mermaid-js.github.io/mermaid/#/flowchart
+    A(("/start")):::entryPoint -->|Hi! My name is Professor Bot...| B((GENDER)):::state
+    B --> |"- Boy <br /> - Girl <br /> - Other"|C("(choice)"):::userInput 
+    C --> |I see! Please send me a photo...| D((PHOTO)):::state
+    D --> E("/skip"):::userInput
+    D --> F("(photo)"):::userInput
+    E --> |I bet you look great!| G[\ /]:::userInput
+    F --> |Gorgeous!| G[\ /]
+    G --> |"Now, send me your location .."| H((LOCATION)):::state
+    H --> I("/skip"):::userInput
+    H --> J("(location)"):::userInput
+    I --> |You seem a bit paranoid!| K[\" "/]:::userInput
+    J --> |Maybe I can visit...| K
+    K --> |"Tell me about yourself..."| L(("BIO")):::state
+    L --> M("(text)"):::userInput
+    M --> |"Thanks and bye!"| End(("END")):::termination
+    classDef userInput  fill:#2a5279, color:#ffffff, stroke:#ffffff
+    classDef state fill:#222222, color:#ffffff, stroke:#ffffff
+    classDef entryPoint fill:#009c11, stroke:#42FF57, color:#ffffff
+    classDef termination fill:#bb0007, stroke:#E60109, color:#ffffff

examples/conversationbot2.mmd

@@ -0,0 +1,17 @@
+flowchart TB
+    %% Documentation: https://mermaid-js.github.io/mermaid/#/flowchart
+    A(("/start")):::entryPoint -->|Hi! My name is Doctor Botter...| B((CHOOSING)):::state
+    B --> C("Something else..."):::userInput 
+    C --> |What category?| D((TYPING_CHOICE)):::state
+    D --> E("(text)"):::userInput
+    E --> |"[save choice] <br /> I'd love to hear about that!"| F((TYPING_REPLY)):::state
+    F --> G("(text)"):::userInput
+    G --> |"[save choice: text] <br /> Neat! <br /> (List of facts) <br /> More?"| B
+    B --> H("- Age <br /> - Favourite colour <br /> - Number of siblings"):::userInput
+    H --> |"[save choice] <br /> I'd love to hear about that!"| F
+    B --> I("Done"):::userInput
+    I --> |"I learned these facts about you: <br /> ..."| End(("END")):::termination
+    classDef userInput  fill:#2a5279, color:#ffffff, stroke:#ffffff
+    classDef state fill:#222222, color:#ffffff, stroke:#ffffff
+    classDef entryPoint fill:#009c11, stroke:#42FF57, color:#ffffff
+    classDef termination fill:#bb0007, stroke:#E60109, color:#ffffff

examples/nestedconversationbot.mmd

@@ -0,0 +1,43 @@
+flowchart TB
+    %% Documentation: https://mermaid-js.github.io/mermaid/#/flowchart
+    A(("/start")):::entryPoint -->|Hi! I'm FamilyBot...| B((SELECTING_ACTION)):::state
+    B --> C("Show Data"):::userInput 
+    C --> |"(List of gathered data)"| D((SHOWING)):::state
+    D --> E("Back"):::userInput
+    E --> B
+    B --> F("Add Yourself"):::userInput
+    F --> G(("DESCRIBING_SELF")):::state
+    G --> H("Add info"):::userInput
+    H --> I((SELECT_FEATURE)):::state
+    I --> |"Please select a feature to update. <br /> - Name <br /> - Age <br /> - Done"|J("(choice)"):::userInput
+    J --> |"Okay, tell me."| K((TYPING)):::state
+    K --> L("(text)"):::userInput
+    L --> |"[saving]"|I
+    I --> M("Done"):::userInput
+    M --> B
+    B --> N("Add family member"):::userInput
+    R --> I
+    W --> |"See you around!"|End(("END")):::termination
+    Y(("ANY STATE")):::state --> Z("/stop"):::userInput
+    Z -->|"Okay, bye."| End
+    B --> W("Done"):::userInput
+    subgraph nestedConversation[Nested Conversation: Add Family Member]
+        direction BT
+        N --> O(("SELECT_LEVEL")):::state
+        O --> |"Add... <br /> - Add Parent <br /> - Add Child <br />"|P("(choice)"):::userInput
+        P -->  Q(("SELECT_GENDER")):::state
+        Q --> |"- Mother <br /> - Father <br /> / <br /> - Sister <br /> - Brother"| R("(choice)"):::userInput
+        Q --> V("Show Data"):::userInput
+        Q --> T(("SELECTING_ACTION")):::state
+        Q --> U("Back"):::userInput
+        U --> T
+        O --> U
+        O --> V
+        V --> S(("SHOWING")):::state
+        V --> T
+    end
+    classDef userInput  fill:#2a5279, color:#ffffff, stroke:#ffffff
+    classDef state fill:#222222, color:#ffffff, stroke:#ffffff
+    classDef entryPoint fill:#009c11, stroke:#42FF57, color:#ffffff
+    classDef termination fill:#bb0007, stroke:#E60109, color:#ffffff
+    style nestedConversation fill:#999999, stroke-width:2px, stroke:#333333