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.

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index bc23deb5f0825edcf8a254b7c3284a189c767d0f..f3fa6e66c544bb0abb982c399dad5b471f30ec68 100644 (file)
--- 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 9ede0eae4119e856f36a4306a467db5b76598a9a..960a945c93e10a15b52c3dbfba9ede285cee099e 100644 (file)
--- 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 8b727a8aa381e033e0a6555d97962862256d7a49..5e5f8d1f6ce245b27ed6e3582cd6ce662376a3c4 100644 (file)
--- 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 74b3dc9810cfcdcc99a1cd0d409a48cf4df17750..52d83e19f1e359da0d7c458d63ae292e84bc2116 100755 (executable)
--- 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