Automate screenshot generation in README.rst

The current screenshot is outdated. It is running on an older version of Django
Debug Toolbar and an end-of-life Django 1.6. Some newer panels, such as the
history panel, are missing.

The new script example/screenshot.py uses Selenium to generate a screenshot
using the latest version of Django and Django Debug Toolbar. Unlike the
previous screenshot which displayed macOS window decorations, this one is
OS-agnostic. The script generates the image with an exact resolution, so
README.rst no longer needs to re-specify dimensions.

The generated image is optimized using the optipng command line utility.

The contributing docs have been updated to include running this script when
making a new release so the screenshot will continue to remain up to date.

Author: jdufresne

Makefile

@@ -47,3 +47,8 @@ translatable_strings:
 update_translations:
 	tx pull -a --minimum-perc=10
 	cd debug_toolbar && python -m django compilemessages
+
+.PHONY: example/django-debug-toolbar.png
+example/django-debug-toolbar.png: example/screenshot.py
+	python $< --browser firefox --headless -o $@
+	optipng $@

README.rst

@@ -25,8 +25,7 @@ more details about the panel's content.
 Here's a screenshot of the toolbar in action:
 
 .. image:: https://raw.github.com/jazzband/django-debug-toolbar/master/example/django-debug-toolbar.png
-   :width: 908
-   :height: 557
+   :alt: Django Debug Toolbar screenshot
 
 In addition to the built-in panels, a number of third-party panels are
 contributed by the community.

docs/contributing.rst

@@ -132,6 +132,14 @@ The release itself requires the following steps:
 
    Commit.
 
+#. Update the screenshot in ``README.rst``.
+
+   .. code-block:: console
+
+       $ make example/django-debug-toolbar.png
+
+   Commit.
+
 #. Bump version numbers in ``docs/changes.rst``, ``docs/conf.py``,
    ``README.rst`` and ``setup.py``. Add the release date to
    ``docs/changes.rst``. Commit.

example/django-debug-toolbar.png

@@ -0,0 +1,83 @@
+import argparse
+import importlib
+import os
+import signal
+import subprocess
+
+from selenium.webdriver.common.keys import Keys
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.support.wait import WebDriverWait
+
+
+def parse_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--browser", required=True)
+    parser.add_argument("--headless", action="store_true")
+    parser.add_argument("--outfile", "-o", required=True)
+    parser.add_argument("--width", type=int, default=900)
+    parser.add_argument("--height", type=int, default=700)
+    return parser.parse_args()
+
+
+def create_webdriver_options(browser, headless):
+    mod = importlib.import_module(f"selenium.webdriver.{browser}.options")
+    options = mod.Options()
+    if headless:
+        options.headless = True
+    return options
+
+
+def create_webdriver(browser, headless):
+    mod = importlib.import_module(f"selenium.webdriver.{browser}.webdriver")
+    return mod.WebDriver(options=create_webdriver_options(browser, headless))
+
+
+def example_server():
+    return subprocess.Popen(["make", "example"])
+
+
+def set_viewport_size(selenium, width, height):
+    script = """
+        return [
+            window.outerWidth - window.innerWidth + arguments[0],
+            window.outerHeight - window.innerHeight + arguments[1],
+        ];
+    """
+    window_width, window_height = selenium.execute_script(script, width, height)
+    selenium.set_window_size(window_width, window_height)
+
+
+def submit_form(selenium, data):
+    url = selenium.current_url
+    for name, value in data.items():
+        el = selenium.find_element_by_name(name)
+        el.send_keys(value)
+    el.send_keys(Keys.RETURN)
+    WebDriverWait(selenium, timeout=5).until(EC.url_changes(url))
+
+
+def main():
+    args = parse_args()
+    with example_server() as p:
+        try:
+            with create_webdriver(args.browser, args.headless) as selenium:
+                set_viewport_size(selenium, args.width, args.height)
+
+                selenium.get("http://localhost:8000/admin/login/")
+                submit_form(selenium, {"username": os.environ["USER"], "password": "p"})
+
+                selenium.get("http://localhost:8000/admin/auth/user/")
+                # Close the admin sidebar.
+                el = selenium.find_element_by_id("toggle-nav-sidebar")
+                el.click()
+                # Open the SQL panel.
+                el = selenium.find_element_by_id("djdt-SQLPanel")
+                el.click()
+
+                selenium.save_screenshot(args.outfile)
+        finally:
+            p.send_signal(signal.SIGTERM)
+
+
+if __name__ == "__main__":
+    main()