Use MermaidJS in admin frontend, make graphviz optional

- Removed graphviz from required dependencies
- Added graphviz as optional dependency (extras: graphviz, docs)
- Added get_graph_mermaid() and get_instance_graph_mermaid() methods
- Updated admin to use MermaidJS for client-side diagram rendering
- Added admin template with MermaidJS CDN for browser rendering
- Reverted all previous Mermaid server-side rendering changes

Co-authored-by: codingjoe <[email protected]>

Author: Copilot

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
       - uses: actions/setup-python@v6
         with:
           python-version: "3.x"
-      - run: sudo apt install -y python3-enchant
+      - run: sudo apt install -y python3-enchant graphviz
       - run: python -m pip install sphinxcontrib-spelling
       - run: python -m pip install -e '.[docs]'
       - run: python -m sphinx -W -b spelling docs docs/_build
@@ -83,7 +83,7 @@ jobs:
       - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
-      - run: sudo apt install -y redis-server
+      - run: sudo apt install -y graphviz redis-server
       - run: python -m pip install "django==${{ matrix.django-version }}.*"
       - run: python -m pip install -e .[${{ matrix.extras }}]
       - run: python -m pytest

.readthedocs.yaml

@@ -8,6 +8,8 @@ build:
   os: ubuntu-20.04
   tools:
     python: "3.11"
+  apt_packages:
+    - graphviz
 
 sphinx:
   configuration: docs/conf.py

docs/commands.rst

@@ -9,8 +9,8 @@ render_workflow_graph
 
 Render workflow graph to file::
 
-    usage: manage.py render_workflow_graph [-h] [-f {svg,mmd,mermaid}] [-d DIRECTORY]
-                                          [workflow [workflow ...]]
+    usage: manage.py render_workflow_graph [-h] [-f {svg,pdf,png}] [-d DIRECTORY]
+                                          [-c] [model [model ...]]
 
     Render workflow graph to file.
 
@@ -20,8 +20,9 @@ Render workflow graph to file::
 
     optional arguments:
       -h, --help            show this help message and exit
-      -f {svg,mmd,mermaid}, --format {svg,mmd,mermaid}
+      -f {svg,pdf,png}, --format {svg,pdf,png}
                             Output file format. Default: svg
       -d DIRECTORY, --directory DIRECTORY
                             Output directory. Default is current working
                             directory.
+      -c, --cleanup         Remove dot-files after rendering.

docs/conf.py

@@ -71,11 +71,14 @@ def linkcode_resolve(domain, info):
     ),
     "dramatiq": ("https://dramatiq.io/", None),
     "celery": ("https://docs.celeryproject.org/en/stable/", None),
+    "graphviz": ("https://graphviz.readthedocs.io/en/stable/", None),
 }
 
 spelling_word_list_filename = "spelling_wordlist.txt"
 spelling_show_suggestions = True
 
+graphviz_output_format = "svg"
+
 inheritance_graph_attrs = dict(
     rankdir="TB", size='"6.0, 8.0"', fontsize=14, ratio="compress"
 )

docs/index.rst

@@ -17,25 +17,22 @@ Django_ web framework.
 Here is a little sample of what a workflow or process written with joeflow
 may look like:
 
-.. code-block:: mermaid
-
-    graph LR
-        checkout(checkout)
-        has_email[has email]
-        ship(ship)
-        end[end]
-        send_tracking_code[send tracking code]
-        checkout --> ship
-        ship --> has_email
-        has_email --> send_tracking_code
-        has_email --> end
-        send_tracking_code --> end
-        style checkout fill:white,stroke:#000,stroke-width:2px,color:#000
-        style has_email fill:white,stroke:#000,stroke-width:2px,color:#000
-        style ship fill:white,stroke:#000,stroke-width:2px,color:#000
-        style end fill:white,stroke:#000,stroke-width:4px,color:#000
-        style send_tracking_code fill:white,stroke:#000,stroke-width:2px,color:#000
-        linkStyle 3 stroke:#888888
+.. graphviz::
+
+    digraph {
+        graph [rankdir=LR]
+        node [fillcolor=white fontname="sans-serif" shape=rect style=filled]
+        checkout [color=black fontcolor=black style="filled, rounded"]
+        "has email" [color=black fontcolor=black style=filled]
+        ship [color=black fontcolor=black style="filled, rounded"]
+        end [color=black fontcolor=black style=filled peripheries=2]
+        "send tracking code" [color=black fontcolor=black style=filled]
+        checkout -> ship
+        ship -> "has email"
+        "has email" -> "send tracking code"
+        "has email" -> end [color="#888888"]
+        "send tracking code" -> end
+    }
 
 .. code-block:: python
 

docs/tutorial/workflow.rst

@@ -8,21 +8,20 @@ user. A human selects the user (or leaves the field blank). If the user is set
 a welcome emails is being sent. If the user is blank no email will be send and
 the workflow will end right way.
 
-.. code-block:: mermaid
-
-    graph LR
-        start(start)
-        send_welcome_email[send welcome email]
-        end[end]
-        has_user[has user]
-        start --> has_user
-        has_user --> end
-        has_user --> send_welcome_email
-        send_welcome_email --> end
-        style start fill:white,stroke:#000,stroke-width:2px,color:#000
-        style send_welcome_email fill:white,stroke:#000,stroke-width:2px,color:#000
-        style end fill:white,stroke:#000,stroke-width:2px,color:#000
-        style has_user fill:white,stroke:#000,stroke-width:2px,color:#000
+.. graphviz::
+
+    digraph {
+        graph [rankdir=LR]
+        node [fillcolor=white fontname="Georgia, serif" shape=rect style=filled]
+        start [color=black fontcolor=black style="filled, rounded"]
+        "send welcome email" [color=black fontcolor=black style=filled]
+        end [color=black fontcolor=black style=filled]
+        "has user" [color=black fontcolor=black style=filled]
+        start -> "has user"
+        "has user" -> end
+        "has user" -> "send welcome email"
+        "send welcome email" -> end
+    }
 
 Let's start with the data structure or workflow state. We need a model that can
 store a user. Like so:

joeflow/admin.py

@@ -147,12 +147,25 @@ def get_inlines(self, *args, **kwargs):
 
     def get_readonly_fields(self, *args, **kwargs):
         return [
-            "get_instance_graph_svg",
+            "display_workflow_diagram",
             *super().get_readonly_fields(*args, **kwargs),
             "modified",
             "created",
         ]
 
+    @admin.display(description="Workflow Diagram")
+    def display_workflow_diagram(self, obj):
+        """Display workflow diagram using MermaidJS for client-side rendering."""
+        if obj.pk:
+            # Get Mermaid diagram syntax
+            mermaid_syntax = obj.get_instance_graph_mermaid()
+            # Wrap in div with mermaid class for client-side rendering
+            return format_html(
+                '<div class="mermaid-diagram"><div class="mermaid">{}</div></div>',
+                mermaid_syntax
+            )
+        return ""
+
     @transaction.atomic()
     def save_model(self, request, obj, form, change):
         super().save_model(request, obj, form, change)

joeflow/management/commands/render_workflow_graph.py

@@ -18,7 +18,7 @@ def add_arguments(self, parser):
             "--format",
             dest="format",
             type=str,
-            choices=("svg", "mmd", "mermaid"),
+            choices=("svg", "pdf", "png"),
             default="svg",
             help="Output file format. Default: svg",
         )
@@ -29,12 +29,19 @@ def add_arguments(self, parser):
             type=str,
             help="Output directory. Default is current working directory.",
         )
-
+        parser.add_argument(
+            "-c",
+            "--cleanup",
+            dest="cleanup",
+            action="store_true",
+            help="Remove dot-files after rendering.",
+        )
 
     def handle(self, *args, **options):
         workflows = options["workflow"]
         verbosity = options["verbosity"]
         file_format = options["format"]
+        cleanup = options["cleanup"]
         directory = options.get("directory", None)
 
         workflows = [
@@ -52,7 +59,8 @@ def handle(self, *args, **options):
                     )
                 filename = f"{opt.app_label}_{workflow.__name__}".lower()
                 graph = workflow.get_graph()
-                graph.render(filename=filename, directory=directory, format=file_format)
+                graph.format = file_format
+                graph.render(filename=filename, directory=directory, cleanup=cleanup)
                 if verbosity > 0:
                     self.stdout.write("Done!", self.style.SUCCESS)
             else: