Hi. Thanks for the PR! Having the state diagram in a text-like format would indeed be nice. Can you explain how one would generate pictures with mermaid and/or how one could embedd those diagrams into the respective examples pages (e.g. here)?
So far I haven't worked much with diagram-generation-software, although one of our emeritus maintainers suggested graphviz on a few occasions …

Hi @Bibo-Joshi, I've used Mermaid since it is supported and rendered in Github in the Markdown view. To include it is as easy as having a code block like ```mermaid ---- mermaid code here ---- ``` You can read more about it in the Github Blog Post. Mermaid is based on JavaScript, I hope that is fine.

• The diagram is a flow chart, I've included a line to link the documentation of flow charts
• To include it on the documentation site you can make a request to the Mermaid API or host it by yourself, here is the full documentation

The sphinx plugin should be enough, no need to self host an API.

If we can integrate the diagrams into sphinx directly, then we should do that and ditch images completely, I agree. Just for completeness: I see that sphinx has built-in support for graphivz, i.e. we wouldn't need a plugin. I'm fine with using a plugin, though.

I've installed the sphinx mermaid extension and embedded it successfully in the docs. However, there are a few things to be aware of:

• The dark mode makes the lines hard to read. This is a known issue at Mermeid and I can only change the color of the lines, not the arrowheads (see here). A quick workaround could be to style Mermaid diagram backgrounds (div with class mermaid) to a lighter grey. Together with some border-radius this can look well integrated within the documentation.
• It would be good to add height: auto to the SVG inside the mermaid div, especially for the nested conversation which seems too wide for the column

Hi, thanks for the updates!

Personally I don't see a problem with darkmode - IMO the lines are rather well visible. I'm attaching screenshots below so that the others can see without having to build the docs :)

Having the nestedconversationbot chart a bit wider would be nice, I agree. Don't recall exactly how one would modify the css here. If it's a small additional snippet for the sphinx config, we can do that. if it's a bigger effort, I'm also okay with user having to zoom in :D

I have some other comments on the layout:

• in the nested conv. diagram, go directly to termination instead of listing "End" as state
• the diagram for conversationbot2.py is missing some sort of exit.
• IMHO the legend is not really necessary. I'm okay with keeping it, but would suggest to do the following (if possible)
  • rename First State to Entry Point & Termination to End
  • adjust the size of entry point & end to be no bigger than State
  • make the "input -> state" left to right instead of top to bottom and list enrty point & end below that - saves some space
• the bright background of the legend and the nested conversation seems off in both bright & dark mode. If possible, please remove.
• in the nested example, it would be nice to have the nested conversation and the main conversation more vertically aligned. I guess that mermaid computes this automatically and that it's hard to fine tune that - just listing for completeness :)

I've included most of the things that you've mentioned plus did some additional improvements. Like you've already guessed, some things are automatically created by Mermaid and I sadly cannot change e.g. the alginment of the nested conversation. A few things to note:

• The background of the nested conversation is grey now which aligns more with the rest of the diagram, fill: none would make it very hard to read the title.
• I have added a small css file to remove the unecessary whitespace of the nested conversation diagram (style_mermaid_diagrams.css)

Thanks for the new updates! I built the docs from your branch locally and everything looks fine to me now :) If I get a LGTM from pool or harshil, we can merge :)

can we remove the old .png diagrams in the examples folder then?

@harshil21 yes 👍

Thank you for the nice cnotribution! :)