diff --git a/AUTHORS.rst b/AUTHORS.rst index 1ba3d6c97..d5565b8c0 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -29,6 +29,7 @@ The following wonderful people contributed directly or indirectly to this projec - `Balduro `_ - `Bibo-Joshi `_ - `bimmlerd `_ +- `cyc8 `_ - `d-qoi `_ - `daimajia `_ - `Daniel Reed `_ diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index d05a421b8..e1b3231bb 100644 --- a/docs/requirements-docs.txt +++ b/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 \ No newline at end of file +sphinx-paramlinks==0.5.4 +sphinxcontrib-mermaid==0.7.1 \ No newline at end of file diff --git a/docs/source/_static/style_mermaid_diagrams.css b/docs/source/_static/style_mermaid_diagrams.css new file mode 100644 index 000000000..23cb8c676 --- /dev/null +++ b/docs/source/_static/style_mermaid_diagrams.css @@ -0,0 +1,3 @@ +.mermaid svg { + height: auto; +} diff --git a/docs/source/conf.py b/docs/source/conf.py index b95f960a8..ce2a1d227 100644 --- a/docs/source/conf.py +++ b/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. diff --git a/docs/source/examples.conversationbot.rst b/docs/source/examples.conversationbot.rst index ebd129ff2..118f9feef 100644 --- a/docs/source/examples.conversationbot.rst +++ b/docs/source/examples.conversationbot.rst @@ -10,5 +10,4 @@ State Diagram ------------- -.. image:: ../../examples/conversationbot.png - \ No newline at end of file +.. mermaid:: ../../examples/conversationbot.mmd diff --git a/docs/source/examples.conversationbot2.rst b/docs/source/examples.conversationbot2.rst index b032cfc75..6219ecaab 100644 --- a/docs/source/examples.conversationbot2.rst +++ b/docs/source/examples.conversationbot2.rst @@ -10,5 +10,4 @@ State Diagram ------------- -.. image:: ../../examples/conversationbot2.png - \ No newline at end of file +.. mermaid:: ../../examples/conversationbot2.mmd diff --git a/docs/source/examples.nestedconversationbot.rst b/docs/source/examples.nestedconversationbot.rst index 48536591d..23c15053d 100644 --- a/docs/source/examples.nestedconversationbot.rst +++ b/docs/source/examples.nestedconversationbot.rst @@ -10,5 +10,4 @@ State Diagram ------------- -.. image:: ../../examples/nestedconversationbot.png - \ No newline at end of file +.. mermaid:: ../../examples/nestedconversationbot.mmd diff --git a/examples/conversationbot.mmd b/examples/conversationbot.mmd new file mode 100644 index 000000000..119d5c0db --- /dev/null +++ b/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
- Girl
- 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 diff --git a/examples/conversationbot.png b/examples/conversationbot.png deleted file mode 100644 index 37dbf431a..000000000 Binary files a/examples/conversationbot.png and /dev/null differ diff --git a/examples/conversationbot2.mmd b/examples/conversationbot2.mmd new file mode 100644 index 000000000..087e539e3 --- /dev/null +++ b/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]
I'd love to hear about that!"| F((TYPING_REPLY)):::state + F --> G("(text)"):::userInput + G --> |"[save choice: text]
Neat!
(List of facts)
More?"| B + B --> H("- Age
- Favourite colour
- Number of siblings"):::userInput + H --> |"[save choice]
I'd love to hear about that!"| F + B --> I("Done"):::userInput + I --> |"I learned these facts about you:
..."| 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 diff --git a/examples/conversationbot2.png b/examples/conversationbot2.png deleted file mode 100644 index 8f02cc94f..000000000 Binary files a/examples/conversationbot2.png and /dev/null differ diff --git a/examples/nestedconversationbot.mmd b/examples/nestedconversationbot.mmd new file mode 100644 index 000000000..edc5a5a89 --- /dev/null +++ b/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.
- Name
- Age
- 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...
- Add Parent
- Add Child
"|P("(choice)"):::userInput + P --> Q(("SELECT_GENDER")):::state + Q --> |"- Mother
- Father
/
- Sister
- 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 diff --git a/examples/nestedconversationbot.png b/examples/nestedconversationbot.png deleted file mode 100644 index 4337040e6..000000000 Binary files a/examples/nestedconversationbot.png and /dev/null differ