From b9a429e6ce11b6e140ce567d6eaeb5132524744f Mon Sep 17 00:00:00 2001
From: Jason Ish <jason.ish@oisf.net>
Date: Mon, 31 Jan 2022 12:06:55 -0600
Subject: [PATCH] devguide: move image generation into sphinx setup

While ReadTheDocs can't execute arbitrary scripts, we can install
mscgen in the container that builds the docs (see .readthedocs.yaml).

Then instead of calling generate-images.sh from the Makefile, move this
into the setup function defined on conf.yaml, which will generate the
scripts as part of a normal Sphinx workflow.

This should give us an image generation solution that works on
ReadTheDocs, and locally within anyones build system provided they have
mscgen installed.
---
 .readthedocs.yaml                     |  4 ++++
 doc/devguide/Makefile.am              |  2 --
 doc/devguide/conf.py                  | 15 ++++++++++-----
 doc/devguide/tools/generate-images.sh |  3 +++
 4 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index bc23deb5f0..f3fa6e66c5 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -7,3 +7,7 @@ python:
   # Use an empty install section to avoid RTD from picking up a non-python
   # requirements.txt file.
   install: []
+
+build:
+  apt_packages:
+    - mscgen
diff --git a/doc/devguide/Makefile.am b/doc/devguide/Makefile.am
index 9ede0eae41..960a945c93 100644
--- a/doc/devguide/Makefile.am
+++ b/doc/devguide/Makefile.am
@@ -34,7 +34,6 @@ endif
 SPHINX_BUILD = sphinx-build -q
 
 html:
-	$(top_srcdir)/doc/devguide/tools/generate-images.sh
 	sysconfdir=$(sysconfdir) \
 	localstatedir=$(localstatedir) \
 	version=$(PACKAGE_VERSION) \
@@ -42,7 +41,6 @@ html:
 		$(top_srcdir)/doc/devguide _build/html
 
 _build/latex/Suricata.pdf:
-	$(top_srcdir)/doc/devguide/tools/generate-images.sh
 	sysconfdir=$(sysconfdir) \
 	localstatedir=$(localstatedir) \
 	version=$(PACKAGE_VERSION) \
diff --git a/doc/devguide/conf.py b/doc/devguide/conf.py
index 8b727a8aa3..5e5f8d1f6c 100644
--- a/doc/devguide/conf.py
+++ b/doc/devguide/conf.py
@@ -13,6 +13,7 @@ import sys
 import os
 import shlex
 import re
+import subprocess
 
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
@@ -128,11 +129,6 @@ if not on_rtd:
         html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
     except:
         html_theme = 'default'
-    def setup(app):
-        if hasattr(app, 'add_css_file'):
-            app.add_css_file('css/suricata.css')
-        else:
-            app.add_stylesheet('css/suricata.css')
 else:
     html_context = {
         'css_files': [
@@ -142,6 +138,15 @@ else:
         ],
     }
 
+def setup(app):
+    # Generate images.
+    subprocess.check_call("./tools/generate-images.sh")
+    if not on_rtd:
+        if hasattr(app, 'add_css_file'):
+            app.add_css_file('css/suricata.css')
+        else:
+            app.add_stylesheet('css/suricata.css')
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
diff --git a/doc/devguide/tools/generate-images.sh b/doc/devguide/tools/generate-images.sh
index 74b3dc9810..52d83e19f1 100755
--- a/doc/devguide/tools/generate-images.sh
+++ b/doc/devguide/tools/generate-images.sh
@@ -3,10 +3,13 @@
 # Script to generate Sequence Diagram images with mscgen
 #
 
+set -e
+
 cd extending/app-layer/diagrams
 
 for FILE in *.msc ; do
     # call mscgen and convert each file in images dir
+    echo "Generating image for $FILE"
     mscgen -T png -F Arial $FILE
     # if command fails, lets inform about that
     if [ $? -ne 0 ]; then
-- 
2.47.2