|
2 | 2 |
|
3 | 3 | import filecmp |
4 | 4 | from os.path import join as pjoin, dirname, isdir |
| 5 | +import pathlib |
5 | 6 | from subprocess import Popen, PIPE |
6 | 7 | import sys |
| 8 | +import warnings |
7 | 9 |
|
8 | 10 | import pytest |
9 | 11 |
|
10 | | - |
| 12 | +# Only run the tests if Sphinx is installed. |
11 | 13 | pytest.importorskip('sphinx') |
12 | 14 |
|
| 15 | +# Docutils is a dependency of Sphinx so it is safe to |
| 16 | +# import after we know Sphinx is available. |
| 17 | +from docutils.nodes import caption, figure |
| 18 | + |
| 19 | +# Sphinx has some deprecation warnings we don't want to turn into errors. |
| 20 | +with warnings.catch_warnings(): |
| 21 | + warnings.simplefilter('ignore') |
| 22 | + from sphinx.application import Sphinx |
| 23 | + |
| 24 | + |
| 25 | +#: Directory of sources for testing the Sphinx extension. |
| 26 | +SRCDIR = pathlib.Path(__file__).parent / 'sphinxext_sources' |
| 27 | + |
| 28 | + |
| 29 | +class NodeFilter: |
| 30 | + """Test utility class to filter nodes from a Sphinx doctree. |
| 31 | +
|
| 32 | + This is designed to be used with the walkabout() method of nodes. You |
| 33 | + probably want to use the filter_children() class method. |
| 34 | +
|
| 35 | + Parameters |
| 36 | + ---------- |
| 37 | + document : node |
| 38 | + The document node. |
| 39 | + classes : list of classes |
| 40 | + The node classes to filter from the document. If None, all classes will |
| 41 | + be accepted resulting in a flattened list of all nodes. |
| 42 | +
|
| 43 | + """ |
| 44 | + def __init__(self, document, classes=None): |
| 45 | + self.document = document |
| 46 | + self.nodes = [] |
| 47 | + if classes: |
| 48 | + self.classes = tuple(classes) |
| 49 | + else: |
| 50 | + self.classes = None |
| 51 | + |
| 52 | + def dispatch_visit(self, obj): |
| 53 | + if not self.classes or isinstance(obj, self.classes): |
| 54 | + self.nodes.append(obj) |
| 55 | + |
| 56 | + def dispatch_departure(self, obj): |
| 57 | + pass |
| 58 | + |
| 59 | + @classmethod |
| 60 | + def filter_children(cls, document, parent, classes=None): |
| 61 | + """Filter child nodes from a parent node. |
| 62 | +
|
| 63 | + Parameters |
| 64 | + ---------- |
| 65 | + document : node |
| 66 | + The main document node. |
| 67 | + parent : node |
| 68 | + The parent node to work on. |
| 69 | + classes : list of classes |
| 70 | + The node classes to filter. |
| 71 | +
|
| 72 | + Returns |
| 73 | + ------- |
| 74 | + children : list |
| 75 | + A list of the nodes which are instances of the given classes or |
| 76 | + their subclasses. |
| 77 | +
|
| 78 | + """ |
| 79 | + obj = cls(document, classes=classes) |
| 80 | + parent.walkabout(obj) |
| 81 | + return obj.nodes |
| 82 | + |
| 83 | + |
| 84 | +def build_test_doc(src_dir, build_dir, builder='html'): |
| 85 | + """Build a test document. |
| 86 | +
|
| 87 | + Parameters |
| 88 | + ---------- |
| 89 | + src_dir : pathlib.Path |
| 90 | + The location of the sources. |
| 91 | + build_dir : pathlib.Path |
| 92 | + The build directory to use. |
| 93 | + builder : str |
| 94 | + Which builder to use. |
| 95 | +
|
| 96 | + Returns |
| 97 | + ------- |
| 98 | + app : sphinx.application.Sphinx |
| 99 | + The Sphinx application that built the document. |
| 100 | +
|
| 101 | + """ |
| 102 | + doctree_dir = build_dir / "doctrees" |
| 103 | + output_dir = build_dir / "html" |
| 104 | + |
| 105 | + # Avoid some internal Sphinx deprecation warnings being turned into errors. |
| 106 | + with warnings.catch_warnings(): |
| 107 | + warnings.simplefilter('ignore') |
| 108 | + app = Sphinx(src_dir, src_dir, output_dir, doctree_dir, builder) |
| 109 | + app.build() |
| 110 | + return app |
| 111 | + |
| 112 | + |
| 113 | +def test_plot_directive_caption(tmpdir): |
| 114 | + """Test the :caption: option of the plot directive. |
| 115 | +
|
| 116 | + """ |
| 117 | + # Build the test document. |
| 118 | + localsrc = SRCDIR / "plot_directive_caption" |
| 119 | + build_dir = pathlib.Path(tmpdir) |
| 120 | + app = build_test_doc(localsrc, build_dir) |
| 121 | + |
| 122 | + # Get the main document and filter out the figures in it. |
| 123 | + index = app.env.get_doctree('index') |
| 124 | + figures = NodeFilter.filter_children(index, index, [figure]) |
| 125 | + |
| 126 | + # The captions we expect to find. |
| 127 | + expected = [ |
| 128 | + None, |
| 129 | + 'Caption for inline plot.', |
| 130 | + None, |
| 131 | + 'This is a caption in the content.', |
| 132 | + 'This is a caption in the options.', |
| 133 | + 'The content caption should be used instead.', |
| 134 | + ] |
| 135 | + |
| 136 | + # N.B., each plot directive generates two figures: |
| 137 | + # one HTML only and one for other builders. |
| 138 | + assert len(figures) == 2 * len(expected), \ |
| 139 | + "Wrong number of figures in document." |
| 140 | + |
| 141 | + # Check the caption nodes are correct. |
| 142 | + for i, figurenode in enumerate(figures): |
| 143 | + n = i // 2 |
| 144 | + captions = NodeFilter.filter_children(index, figurenode, [caption]) |
| 145 | + |
| 146 | + if expected[n]: |
| 147 | + assert len(captions) > 0, f"Figure {n+1}: no caption found." |
| 148 | + assert len(captions) < 2, f"Figure {n+1}: too many captions." |
| 149 | + assert captions[0].astext().strip() == expected[n], \ |
| 150 | + f"Figure {n+1}: wrong caption" |
| 151 | + else: |
| 152 | + assert len(captions) == 0, f"Figure {n+1}: unexpected caption." |
| 153 | + |
13 | 154 |
|
14 | 155 | def test_tinypages(tmpdir): |
15 | 156 | html_dir = pjoin(str(tmpdir), 'html') |
|
0 commit comments