Include figures in PDF docs

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

@@ -7,6 +7,10 @@ python:
       - method: pip
         path: .
 
+build:
+  apt_packages:
+    - inkscape
+
 formats:
   - epub
   - pdf

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.

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"/>

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">

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" />

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 -->

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>

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">

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``

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