From e929d15848da4d538f70a830f642a7bf913feaab Mon Sep 17 00:00:00 2001
From: Andrew Neitsch <andrew@neitsch.ca>
Date: Thu, 2 Sep 2021 17:40:41 -0600
Subject: [PATCH] Include figures in PDF docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The PDF documentation on readthedocs was missing the figures in the
fixtures reference chapter. This PR uses a Sphinx plugin that
automatically converts the checked-in SVG files to the PDF input files
that LaTeX requires.

The SVG-to-PDF conversion is done by inkscape, which gave the best
conversion among the tools I tried. However, it [does not yet
understand][href-bug] that you can write a plain `href` instead of
`xlink:href` in svg files, so I’ve had to edit the SVG files
accordingly.

[href-bug]: https://github.com/TeX-Live/luatex.git
---
 .readthedocs.yml                               |  4 ++++
 doc/en/conf.py                                 |  1 +
 .../example/fixtures/fixture_availability.svg  | 10 +++++-----
 .../fixtures/fixture_availability_plugins.svg  | 12 ++++++------
 ..._fixtures_order_autouse_multiple_scopes.svg |  6 +++---
 ...est_fixtures_order_autouse_temp_effects.svg |  6 +++---
 .../fixtures/test_fixtures_order_scope.svg     |  4 ++--
 .../test_fixtures_request_different_scope.svg  |  8 ++++----
 doc/en/reference/fixtures.rst                  | 18 +++++++++---------
 doc/en/requirements.txt                        |  1 +
 10 files changed, 38 insertions(+), 32 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 0176c2640..10c21fd8f 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -7,6 +7,10 @@ python:
       - method: pip
         path: .
 
+build:
+  apt_packages:
+    - inkscape
+
 formats:
   - epub
   - pdf
diff --git a/doc/en/conf.py b/doc/en/conf.py
index ee71ffcae..35941080b 100644
--- a/doc/en/conf.py
+++ b/doc/en/conf.py
@@ -55,6 +55,7 @@ extensions = [
     "sphinx.ext.viewcode",
     "sphinx_removed_in",
     "sphinxcontrib_trio",
+    "sphinxcontrib.inkscapeconverter",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/doc/en/example/fixtures/fixture_availability.svg b/doc/en/example/fixtures/fixture_availability.svg
index 3ca28447c..066caac34 100644
--- a/doc/en/example/fixtures/fixture_availability.svg
+++ b/doc/en/example/fixtures/fixture_availability.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="572" height="542">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="572" height="542">
     <style>
         text {
             font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
@@ -37,7 +37,7 @@
         <path d="M 26,271 A 260 260 0 0 1 546 271" id="testp"/>
     </defs>
     <text class="package">
-        <textPath href="#testp" startOffset="50%">tests</textPath>
+        <textPath xlink:href="#testp" startOffset="50%">tests</textPath>
     </text>
 
     <!-- subpackage -->
@@ -47,7 +47,7 @@
         <path d="M 56,271 A 130 130 0 0 1 316 271" id="subpackage"/>
     </defs>
     <text class="package">
-        <textPath href="#subpackage" startOffset="50%">subpackage</textPath>
+        <textPath xlink:href="#subpackage" startOffset="50%">subpackage</textPath>
     </text>
 
     <!-- test_subpackage.py -->
@@ -57,7 +57,7 @@
         <path d="M 106,311 A 80 80 0 0 1 266 311" id="testSubpackage"/>
     </defs>
     <text class="module">
-        <textPath href="#testSubpackage" startOffset="50%">test_subpackage.py</textPath>
+        <textPath xlink:href="#testSubpackage" startOffset="50%">test_subpackage.py</textPath>
     </text>
     <!-- innermost -->
     <line x1="186" x2="186" y1="271" y2="351"/>
@@ -102,7 +102,7 @@
         <path d="M 366,271 A 75 75 0 0 1 516 271" id="testTop"/>
     </defs>
     <text class="module">
-        <textPath href="#testTop" startOffset="50%">test_top.py</textPath>
+        <textPath xlink:href="#testTop" startOffset="50%">test_top.py</textPath>
     </text>
     <!-- innermost -->
     <line x1="441" x2="441" y1="306" y2="236"/>
diff --git a/doc/en/example/fixtures/fixture_availability_plugins.svg b/doc/en/example/fixtures/fixture_availability_plugins.svg
index 88e32d908..36e300550 100644
--- a/doc/en/example/fixtures/fixture_availability_plugins.svg
+++ b/doc/en/example/fixtures/fixture_availability_plugins.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="587" height="382">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="587" height="382">
     <style>
         text {
             font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
@@ -38,7 +38,7 @@
         <path d="M 411,86 A 75 75 0 0 1 561 86" id="pluginA"/>
     </defs>
     <text class="plugin">
-        <textPath href="#pluginA" startOffset="50%">plugin_a</textPath>
+        <textPath xlink:href="#pluginA" startOffset="50%">plugin_a</textPath>
     </text>
     <!-- scope order number -->
     <mask id="pluginAOrderMask">
@@ -55,7 +55,7 @@
         <path d="M 411,296 A 75 75 0 0 1 561 296" id="pluginB"/>
     </defs>
     <text class="plugin">
-        <textPath href="#pluginB" startOffset="50%">plugin_b</textPath>
+        <textPath xlink:href="#pluginB" startOffset="50%">plugin_b</textPath>
     </text>
     <!-- scope order number -->
     <mask id="pluginBOrderMask">
@@ -72,7 +72,7 @@
         <path d="M 11,191 A 180 180 0 0 1 371 191" id="testp"/>
     </defs>
     <text class="package">
-        <textPath href="#testp" startOffset="50%">tests</textPath>
+        <textPath xlink:href="#testp" startOffset="50%">tests</textPath>
     </text>
     <!-- scope order number -->
     <mask id="mainOrderMask">
@@ -89,7 +89,7 @@
         <path d="M 61,231 A 130 130 0 0 1 321 231" id="subpackage"/>
     </defs>
     <text class="package">
-        <textPath href="#subpackage" startOffset="50%">subpackage</textPath>
+        <textPath xlink:href="#subpackage" startOffset="50%">subpackage</textPath>
     </text>
     <!-- scope order number -->
     <mask id="subpackageOrderMask">
@@ -106,7 +106,7 @@
         <path d="M 111,271 A 80 80 0 0 1 271 271" id="testSubpackage"/>
     </defs>
     <text class="module">
-        <textPath href="#testSubpackage" startOffset="50%">test_subpackage.py</textPath>
+        <textPath xlink:href="#testSubpackage" startOffset="50%">test_subpackage.py</textPath>
     </text>
     <!-- scope order number -->
     <mask id="testSubpackageOrderMask">
diff --git a/doc/en/example/fixtures/test_fixtures_order_autouse_multiple_scopes.svg b/doc/en/example/fixtures/test_fixtures_order_autouse_multiple_scopes.svg
index 9f2180fe5..fe5772993 100644
--- a/doc/en/example/fixtures/test_fixtures_order_autouse_multiple_scopes.svg
+++ b/doc/en/example/fixtures/test_fixtures_order_autouse_multiple_scopes.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="862" height="402">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="862" height="402">
     <style>
         text {
             font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
@@ -48,7 +48,7 @@
         <path d="M31,201 A 190 190 0 0 1 411 201" id="testClassWith"/>
     </defs>
     <text class="class">
-        <textPath href="#testClassWith" startOffset="50%">TestWithC1Request</textPath>
+        <textPath xlink:href="#testClassWith" startOffset="50%">TestWithC1Request</textPath>
     </text>
 
     <!-- TestWithoutC1Request -->
@@ -67,7 +67,7 @@
         <path d="M451,201 A 190 190 0 0 1 831 201" id="testClassWithout"/>
     </defs>
     <text class="class">
-        <textPath href="#testClassWithout" startOffset="50%">TestWithoutC1Request</textPath>
+        <textPath xlink:href="#testClassWithout" startOffset="50%">TestWithoutC1Request</textPath>
     </text>
 
     <rect class="autouse" width="862" height="40" x="1" y="181" />
diff --git a/doc/en/example/fixtures/test_fixtures_order_autouse_temp_effects.svg b/doc/en/example/fixtures/test_fixtures_order_autouse_temp_effects.svg
index ac62ae46b..2a9f51673 100644
--- a/doc/en/example/fixtures/test_fixtures_order_autouse_temp_effects.svg
+++ b/doc/en/example/fixtures/test_fixtures_order_autouse_temp_effects.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="862" height="502">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="862" height="502">
     <style>
         text {
             font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
@@ -39,7 +39,7 @@
         <path d="M11,251 A 240 240 0 0 1 491 251" id="testClassWith"/>
     </defs>
     <text class="class">
-        <textPath href="#testClassWith" startOffset="50%">TestWithAutouse</textPath>
+        <textPath xlink:href="#testClassWith" startOffset="50%">TestWithAutouse</textPath>
     </text>
     <mask id="autouseScope">
         <circle fill="white" r="249" cx="251" cy="251" />
@@ -79,7 +79,7 @@
         <path d="M 531,251 A 160 160 0 0 1 851 251" id="testClassWithout"/>
     </defs>
     <text class="class">
-        <textPath href="#testClassWithout" startOffset="50%">TestWithoutAutouse</textPath>
+        <textPath xlink:href="#testClassWithout" startOffset="50%">TestWithoutAutouse</textPath>
     </text>
 
     <!-- TestWithoutAutouse.test_req -->
diff --git a/doc/en/example/fixtures/test_fixtures_order_scope.svg b/doc/en/example/fixtures/test_fixtures_order_scope.svg
index ebaf7e4e2..f38ee60f1 100644
--- a/doc/en/example/fixtures/test_fixtures_order_scope.svg
+++ b/doc/en/example/fixtures/test_fixtures_order_scope.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="262" height="537">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="262" height="537">
     <style>
         text {
             font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
@@ -50,6 +50,6 @@
         <path d="M131,526 A 120 120 0 0 1 136 286" id="testClass"/>
     </defs>
     <text class="class">
-        <textPath href="#testClass" startOffset="50%">TestClass</textPath>
+        <textPath xlink:href="#testClass" startOffset="50%">TestClass</textPath>
     </text>
 </svg>
diff --git a/doc/en/example/fixtures/test_fixtures_request_different_scope.svg b/doc/en/example/fixtures/test_fixtures_request_different_scope.svg
index ad98469ce..0a78a889f 100644
--- a/doc/en/example/fixtures/test_fixtures_request_different_scope.svg
+++ b/doc/en/example/fixtures/test_fixtures_request_different_scope.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="562" height="532">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="562" height="532">
     <style>
         text {
             font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
@@ -41,7 +41,7 @@
         <path d="M 26,266 A 255 255 0 0 1 536 266" id="testModule"/>
     </defs>
     <text class="module">
-        <textPath href="#testModule" startOffset="50%">test_fixtures_request_different_scope.py</textPath>
+        <textPath xlink:href="#testModule" startOffset="50%">test_fixtures_request_different_scope.py</textPath>
     </text>
 
     <!-- TestOne -->
@@ -61,7 +61,7 @@
         <path d="M 51,266 A 90 90 0 0 1 231 266" id="testOne"/>
     </defs>
     <text class="class">
-        <textPath href="#testOne" startOffset="50%">TestOne</textPath>
+        <textPath xlink:href="#testOne" startOffset="50%">TestOne</textPath>
     </text>
     <!-- scope order number -->
     <mask id="testOneOrderMask">
@@ -95,7 +95,7 @@
         <path d="M 331,266 A 90 90 0 0 1 511 266" id="testTwo"/>
     </defs>
     <text class="class">
-        <textPath href="#testTwo" startOffset="50%">TestTwo</textPath>
+        <textPath xlink:href="#testTwo" startOffset="50%">TestTwo</textPath>
     </text>
     <!-- scope order number -->
     <mask id="testTwoOrderMask">
diff --git a/doc/en/reference/fixtures.rst b/doc/en/reference/fixtures.rst
index a333598a9..35b790212 100644
--- a/doc/en/reference/fixtures.rst
+++ b/doc/en/reference/fixtures.rst
@@ -116,7 +116,7 @@ fixture (``inner``) from a scope it wasn't defined in:
 From the tests' perspectives, they have no problem seeing each of the fixtures
 they're dependent on:
 
-.. image:: /example/fixtures/test_fixtures_request_different_scope.svg
+.. image:: /example/fixtures/test_fixtures_request_different_scope.*
     :align: center
 
 So when they run, ``outer`` will have no problem finding ``inner``, because
@@ -193,7 +193,7 @@ For example, given a test file structure like this:
 
 The boundaries of the scopes can be visualized like this:
 
-.. image:: /example/fixtures/fixture_availability.svg
+.. image:: /example/fixtures/fixture_availability.*
     :align: center
 
 The directories become their own sort of scope where fixtures that are defined
@@ -319,7 +319,7 @@ The test will pass because the larger scoped fixtures are executing first.
 
 The order breaks down to this:
 
-.. image:: /example/fixtures/test_fixtures_order_scope.svg
+.. image:: /example/fixtures/test_fixtures_order_scope.*
     :align: center
 
 Fixtures of the same order execute based on dependencies
@@ -337,13 +337,13 @@ For example:
 
 If we map out what depends on what, we get something that look like this:
 
-.. image:: /example/fixtures/test_fixtures_order_dependencies.svg
+.. image:: /example/fixtures/test_fixtures_order_dependencies.*
     :align: center
 
 The rules provided by each fixture (as to what fixture(s) each one has to come
 after) are comprehensive enough that it can be flattened to this:
 
-.. image:: /example/fixtures/test_fixtures_order_dependencies_flat.svg
+.. image:: /example/fixtures/test_fixtures_order_dependencies_flat.*
     :align: center
 
 Enough information has to be provided through these requests in order for pytest
@@ -354,7 +354,7 @@ could go with any one of those interpretations at any point.
 
 For example, if ``d`` didn't request ``c``, i.e.the graph would look like this:
 
-.. image:: /example/fixtures/test_fixtures_order_dependencies_unclear.svg
+.. image:: /example/fixtures/test_fixtures_order_dependencies_unclear.*
     :align: center
 
 Because nothing requested ``c`` other than ``g``, and ``g`` also requests ``f``,
@@ -395,7 +395,7 @@ So if the test file looked like this:
 
 the graph would look like this:
 
-.. image:: /example/fixtures/test_fixtures_order_autouse.svg
+.. image:: /example/fixtures/test_fixtures_order_autouse.*
     :align: center
 
 Because ``c`` can now be put above ``d`` in the graph, pytest can once again
@@ -413,7 +413,7 @@ example, consider this file:
 Even though nothing in ``TestClassWithoutC1Request`` is requesting ``c1``, it still
 is executed for the tests inside it anyway:
 
-.. image:: /example/fixtures/test_fixtures_order_autouse_multiple_scopes.svg
+.. image:: /example/fixtures/test_fixtures_order_autouse_multiple_scopes.*
     :align: center
 
 But just because one autouse fixture requested a non-autouse fixture, that
@@ -428,7 +428,7 @@ For example, take a look at this test file:
 
 It would break down to something like this:
 
-.. image:: /example/fixtures/test_fixtures_order_autouse_temp_effects.svg
+.. image:: /example/fixtures/test_fixtures_order_autouse_temp_effects.*
     :align: center
 
 For ``test_req`` and ``test_no_req`` inside ``TestClassWithAutouse``, ``c3``
diff --git a/doc/en/requirements.txt b/doc/en/requirements.txt
index 2cd1fc25e..5b49cb7fc 100644
--- a/doc/en/requirements.txt
+++ b/doc/en/requirements.txt
@@ -4,3 +4,4 @@ pygments-pytest>=2.2.0
 sphinx-removed-in>=0.2.0
 sphinx>=3.1,<4
 sphinxcontrib-trio
+sphinxcontrib-svg2pdfconverter