More unit tests

.github/workflows/tests.yml

@@ -11,8 +11,14 @@ permissions:
 
 jobs:
   pytest:
-    name: Run pytest
+    name: Run pytest${{ matrix.litehtml && ' with litehtmlpy' || '' }}
     runs-on: ubuntu-latest
+    strategy:
+      # litehtmlpy is not on PyPI and is built from source, so a failing
+      # build must not hide the results of the plain run.
+      fail-fast: false
+      matrix:
+        litehtml: [false, true]
 
     steps:
       - name: Checkout
@@ -24,13 +30,43 @@ jobs:
             python3-docutils \
             python3-gi \
             python3-jsonpath-ng \
+            python3-pip \
             python3-pytest \
+            python3-venv \
             gir1.2-adw-1 \
             gir1.2-gtksource-5 \
             gir1.2-spelling-1 \
             gir1.2-webkit-6.0
+      - name: Install build dependencies of litehtmlpy
+        if: matrix.litehtml
+        run: |
+          sudo apt-get install --no-install-recommends --yes \
+            build-essential \
+            cmake \
+            git \
+            libcairo2-dev \
+            libpango1.0-dev \
+            ninja-build \
+            pybind11-dev \
+            python3-cairo \
+            python3-dev
+      - name: Install optional Python dependencies
+        run: |
+          python3 -m venv --system-site-packages "$RUNNER_TEMP/venv"
+          # Not `.[extra]`: it lists docutils-htmlwriter, which is not on PyPI.
+          "$RUNNER_TEMP/venv/bin/pip" install \
+            pynvim m2r2 mistune Pygments docutils-tinyhtmlwriter
+      - name: Build litehtmlpy
+        if: matrix.litehtml
+        # The same source as the `litehtml` extra in pyproject.toml, without
+        # installing formiko itself: the tests must import the checkout.
+        run: |
+          "$RUNNER_TEMP/venv/bin/pip" install \
+            'litehtmlpy @ git+https://github.com/m32/litehtmlpy.git'
       - name: Run tests
-        run: env -u DISPLAY -u WAYLAND_DISPLAY python3 -m pytest -m "not gtk_integration" -q
+        run: |
+          env -u DISPLAY -u WAYLAND_DISPLAY \
+            "$RUNNER_TEMP/venv/bin/python" -m pytest -m "not gtk_integration" -q -rs
   gtk-integration:
     name: Run GTK integration tests
     runs-on: ubuntu-latest

CONTRIBUTION.rst

@@ -113,6 +113,40 @@ tests.
 full suite, including GTK integration tests, requires the private Mutter
 headless compositor described above.
 
+**Beware, unsetting the variables is not enough locally.** On a desktop
+session GTK still finds the compositor's socket through
+``XDG_RUNTIME_DIR`` (``$XDG_RUNTIME_DIR/wayland-0``) and connects to it, so
+the command above can pass on a developer machine and still crash in CI,
+where there is no display at all. To reproduce CI, hide the socket too::
+
+    env -u DISPLAY -u WAYLAND_DISPLAY XDG_RUNTIME_DIR=$(mktemp -d) \
+        python3 -m pytest -m "not gtk_integration" -q
+
+Without a display, ``Gdk.Display.get_default()`` and
+``Gtk.Settings.get_default()`` return ``None`` and constructing a real
+widget can crash the interpreter with a segmentation fault instead of
+raising. A crash has no Python traceback in the CI log, only
+``Segmentation fault (core dumped)``; run with ``-v`` to see the test that
+was running, and note that pytest may lose the ``faulthandler`` output (see
+below). Typical offenders and what to do instead:
+
+* Do not build widgets such as ``Renderer`` (a ``Gtk.Overlay``) or
+  ``Adw.*`` windows and dialogs in a plain test. Borrow the method under
+  test from the class and call it on a ``types.SimpleNamespace`` adapter
+  (see ``tests/test_renderer_logic.py`` and
+  ``tests/test_renderer_scroll_sync.py``), or move the test to the
+  ``gtk_integration`` job. These objects have been observed to work
+  without a display: ``Gtk.FileFilter``, ``Gio.ListStore``,
+  ``GtkSource.Buffer``, ``Gdk.RGBA`` and ``Adw.Application``. That is
+  what the CI runs have shown so far, not a guarantee, so run the
+  ``XDG_RUNTIME_DIR`` command above before relying on anything else.
+* Keep the adapter for ``Renderer`` in one place,
+  ``tests/renderer_adapter.py``, rather than copying its private
+  attributes into each test.
+* Do not import ``formiko.__main__`` at module level in a test: it calls
+  ``faulthandler.enable()`` on import, which redirects the crash dump into
+  pytest's captured stderr, so a segfault leaves no trace in the log.
+
 Commits
 -------
 

ChangeLog

@@ -3,6 +3,7 @@ Changelog
 
 Version 2.1.0.dev
 
+  * Fix the mdinclude directive failing with the newest m2r2 (2.1)
   * Add desktop actions to open documents in a new window or as new tabs
     in an existing window
   * Add a "Mistune Markdown" parser option: renders Markdown straight to

formiko/directives.py

@@ -33,11 +33,15 @@ class _M2RConfig:
         m2r_parse_relative_links = False
         m2r_anonymous_references = False
         m2r_disable_inline_math = False
+        m2r_inline_math = "legacy"  # m2r2 >= 2.1, same as the old default
         m2r_use_mermaid = False
 
     class _M2REnv:
         config = _M2RConfig()
 
+        def note_included(self, filename):
+            """Ignore the Sphinx hook that m2r2 >= 2.1 calls on include."""
+
     class StandaloneMdInclude(MdInclude):
         """MdInclude with standalone docutils support.
 

formiko/renderer.py

@@ -563,7 +563,7 @@ def render_output(self):  # noqa: C901, PLR0911
                     "source": self.src,
                     "source_path": self.file_name,
                     "parser": self.parser_instance,
-                    "writer": self.writer_instance or "html",
+                    "writer": self.writer_instance,
                     "settings_overrides": settings,
                 }
                 if self.__writer["key"] == "pep":

formiko/user.py

@@ -25,7 +25,9 @@ class View:
     def __new__(cls, value):
         """Create enum value from string or number value."""
         value = int(value)
-        assert 0 < value < View.BOTH + 1
+        if not View.EDITOR <= value <= View.BOTH:
+            msg = f"{value} is not a valid view"
+            raise ValueError(msg)
         return value
 
 

tests/renderer_adapter.py

@@ -0,0 +1,31 @@
+"""Duck-typed stand-in for :class:`formiko.renderer.Renderer`.
+
+``Renderer`` is a ``Gtk.Overlay`` and cannot be built without a display
+(the constructor segfaults), so tests borrow methods from the class and run
+them against this adapter. Keep the knowledge of which private attributes
+``render_output`` reads, including the name-mangled ones, in this one place.
+
+Import it after ``gi.require_version`` has been called.
+"""
+
+from types import SimpleNamespace
+
+from formiko.renderer import PARSERS, WRITERS, Renderer
+
+
+def make_render_adapter(parser="rst", writer="html4", **overrides):
+    """Return an adapter that ``Renderer.render_output`` can run against."""
+    adapter = SimpleNamespace(
+        src="Title\n=====\n\ntext\n",
+        file_name="/tmp/x.rst",  # noqa: S108
+        tab_width=8,
+        style="",
+        parser_instance=PARSERS[parser]["class"](),
+        writer_instance=WRITERS[writer]["class"](),
+        _embed_stylesheet=Renderer._embed_stylesheet,
+    )
+    adapter._Renderer__parser = PARSERS[parser]
+    adapter._Renderer__writer = WRITERS[writer]
+    for key, value in overrides.items():
+        setattr(adapter, key, value)
+    return adapter