p53209761
/
test_ok2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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
This commit is contained in:
Andrew Neitsch 2021-09-02 17:40:41 -06:00
parent 20863c3a0c
commit e929d15848
10 changed files with 38 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.readthedocs.yml
View File

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

1
doc/en/conf.py
View File

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

10
doc/en/example/fixtures/fixture_availability.svg
View File

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

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.9 KiB

After

Width:  |  Height:  |  Size: 5.0 KiB

12
doc/en/example/fixtures/fixture_availability_plugins.svg
View File

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

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.3 KiB

After

Width:  |  Height:  |  Size: 5.4 KiB

6
doc/en/example/fixtures/test_fixtures_order_autouse_multiple_scopes.svg
View File

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

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.6 KiB

After

Width:  |  Height:  |  Size: 2.6 KiB

6
doc/en/example/fixtures/test_fixtures_order_autouse_temp_effects.svg
View File

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

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.5 KiB

After

Width:  |  Height:  |  Size: 3.6 KiB

4
doc/en/example/fixtures/test_fixtures_order_scope.svg
View File

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

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.8 KiB

After

Width:  |  Height:  |  Size: 1.9 KiB

8
doc/en/example/fixtures/test_fixtures_request_different_scope.svg
View File

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

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.2 KiB

After

Width:  |  Height:  |  Size: 4.3 KiB

18
doc/en/reference/fixtures.rst
View File

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

1
doc/en/requirements.txt
View File

@ -4,3 +4,4 @@ pygments-pytest>=2.2.0
sphinx-removed-in>=0.2.0
sphinx>=3.1,<4
sphinxcontrib-trio
sphinxcontrib-svg2pdfconverter