Newer
Older
from base import BaseDirective
from sphinx.locale import _
import os
class InterfaceDirective(BaseDirective):
"""
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
It requires a SCREENSHOTS_DIR environment variable to be set to the
directory where a screenshot should be generated. If it is not set then
a RuntimeError occurs
"""
required_arguments, optional_arguments = 1, 0
def run(self):
"""
The main entry point that docutils calls.
It calls self.execute to do the main work.
Derived classes should override execute() and insert
whatever rst they require with self.add_rst()
"""
nodes = self.execute()
if self.rst_lines is not None:
self.commit_rst()
return nodes
def execute(self):
"""
Called by Sphinx when the ..interface:: directive is encountered
"""
picture = self._create_screenshot()
self._insert_screenshot_link(picture)
return []
def interface_name(self):
return self.arguments[0]
def _create_screenshot(self):
"""
Creates a screenshot for the named interface in the "images/screenshots"
subdirectory.
The file will be named "interfacename_interface.png", e.g. "ISIS_Reflectometry_interface.png"
Returns:
screenshot: A mantiddoc.tools.Screenshot object
"""
try:
screenshots_dir = self._screenshot_directory()
except RuntimeError:
return None
# Generate image
from mantiddoc.tools.screenshot import custominterface_screenshot
if not os.path.exists(screenshots_dir):
os.makedirs(screenshots_dir)
try:
picture = custominterface_screenshot(self.interface_name(), screenshots_dir)
except RuntimeError, exc:
env = self.state.document.settings.env
env.warn(env.docname, "Unable to generate screenshot for '%s' - %s" % (self.interface_name(), str(exc)))
picture = None
return picture
def _insert_screenshot_link(self, picture):
"""
Outputs an image link with a custom :class: style. The filename is
extracted from the path given and then a relative link to the
directory specified by the SCREENSHOTS_DIR environment variable from
the root source directory is formed.
Args:
picture (Screenshot): A Screenshot object
"""
env = self.state.document.settings.env
format_str = ".. figure:: %s\n"\
" :class: screenshot\n"\
" :width: %dpx\n"\
" :align: left\n\n"\
" %s\n\n"
# Sphinx assumes that an absolute path is actually relative to the directory containing the
# conf.py file and a relative path is relative to the directory where the current rst file
# is located.
if picture:
screenshots_dir, filename = os.path.split(picture.imgpath)
# Find the width of the image
width, height = picture.width, picture.height
# relative path to image
rel_path = os.path.relpath(screenshots_dir, env.srcdir)
# This is a href link so is expected to be in unix style
rel_path = rel_path.replace("\\","/")
# stick a "/" as the first character so Sphinx computes relative location from source directory
path = "/" + rel_path + "/" + filename
else:
# use stock not found image
path = "/images/ImageNotFound.png"
width = 200
caption = "**" + self.interface_name() + "** interface."
self.add_rst(format_str % (path, width, caption))
def _screenshot_directory(self):
"""
Returns a full path where the screenshots should be generated. They are
put in a screenshots subdirectory of the main images directory in the source
tree. Sphinx then handles copying them to the final location
Arguments:
env (BuildEnvironment): Allows access to find the source directory
Returns:
str: A string containing a path to where the screenshots should be created. This will
be a filesystem path
"""
try:
return os.environ["SCREENSHOTS_DIR"]
except:
raise RuntimeError("The '.. interface::' directive requires a SCREENSHOTS_DIR environment variable to be set.")
#------------------------------------------------------------------------------------------------------------
def setup(app):
"""
Setup the directives when the extension is activated
Args:
app: The main Sphinx application object
"""
app.add_directive('interface', InterfaceDirective)