-
Notifications
You must be signed in to change notification settings - Fork 0
/
DocumentationGuideForDevs.html
374 lines (332 loc) · 28.3 KB
/
DocumentationGuideForDevs.html
1
2
3
4
5
6
7
8
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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Documentation Guide for Devs</title>
<link rel="stylesheet" href="_static/basic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-3.3.6/css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-3.3.6/css/bootstrap-theme.min.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '3.12.20180329.1038',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.3.6/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-59110517-1', 'auto');
ga('send', 'pageview');
</script>
</head>
<body role="document">
<div id="navbar" class="navbar navbar-default ">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="http://www.mantidproject.org"><img src="_static/Mantid_Logo_Transparent.png">
</a>
<span class="navbar-text navbar-version pull-left"><b>3.12</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="divider-vertical"></li>
<li><a href="http://www.mantidproject.org">Home</a></li>
<li><a href="http://download.mantidproject.org">Download</a></li>
<li><a href="http://www.mantidproject.org/Documentation">Documentation</a></li>
<li><a href="http://www.mantidproject.org/Contact">Contact Us</a></li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-12 content">
<div class="section" id="documentation-guide-for-devs">
<span id="documentationguidefordevs"></span><h1>Documentation Guide for Devs<a class="headerlink" href="#documentation-guide-for-devs" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#rationale" id="id1">Rationale</a></li>
<li><a class="reference internal" href="#prerequisites" id="id2">Prerequisites</a><ul>
<li><a class="reference internal" href="#sphinx" id="id3">Sphinx</a></li>
<li><a class="reference internal" href="#latex" id="id4">LaTeX</a><ul>
<li><a class="reference internal" href="#linux" id="id5">Linux</a></li>
<li><a class="reference internal" href="#macos" id="id6">MacOS</a></li>
<li><a class="reference internal" href="#windows" id="id7">Windows</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#rest-editors-ide-plugins" id="id8">reST editors/IDE plugins</a><ul>
<li><a class="reference internal" href="#restview" id="id9">Restview</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-restructuredtext-file" id="id10">The reStructuredText File</a><ul>
<li><a class="reference internal" href="#directives" id="id11">Directives</a></li>
<li><a class="reference internal" href="#comments" id="id12">Comments</a></li>
<li><a class="reference internal" href="#algorithms" id="id13">Algorithms</a></li>
<li><a class="reference internal" href="#interfaces" id="id14">Interfaces</a></li>
<li><a class="reference internal" href="#how-to-define-titles-sections-etc" id="id15">How to define titles, sections etc.</a></li>
</ul>
</li>
<li><a class="reference internal" href="#things-to-avoid" id="id16">Things to Avoid</a><ul>
<li><a class="reference internal" href="#common-warnings-and-fixes" id="id17">Common Warnings and Fixes</a><ul>
<li><a class="reference internal" href="#explicit-markup-ends-without-a-blank-line-unexpected-unindent" id="id18">Explicit markup ends without a blank line; unexpected unindent.</a></li>
<li><a class="reference internal" href="#inline-interpreted-text-or-phrase-reference-start-string-without-end-string" id="id19">Inline interpreted text or phrase reference start-string without end-string</a></li>
<li><a class="reference internal" href="#image-file-not-readable" id="id20">image file not readable</a></li>
<li><a class="reference internal" href="#unknown-directive-type-foo" id="id21">Unknown directive type “foo”</a></li>
<li><a class="reference internal" href="#warnings-on-console-in-the-build-servers" id="id22">Warnings on console (in the build servers)</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#running-documentation-tests-locally" id="id23">Running documentation tests locally</a></li>
</ul>
</div>
<div class="section" id="rationale">
<h2><a class="toc-backref" href="#id1">Rationale</a><a class="headerlink" href="#rationale" title="Permalink to this headline">¶</a></h2>
<p>The algorithm documentation approach aims to:</p>
<ol class="arabic simple">
<li>Keep .cpp files clean and easy to maintain.</li>
<li>Make the documentation files easier to edit, supporting the use of external editors.</li>
<li>Simplify the Mantid documentation workflow.</li>
</ol>
<p>To do this we have harmonised most of our documentation workflow to use sphinx, extended a bit by some Mantid custom tag extensions.</p>
</div>
<div class="section" id="prerequisites">
<h2><a class="toc-backref" href="#id2">Prerequisites</a><a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2>
<p>The documentation build requires:</p>
<div class="section" id="sphinx">
<h3><a class="toc-backref" href="#id3">Sphinx</a><a class="headerlink" href="#sphinx" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><a class="reference external" href="http://www.sphinx-doc.org/en/master/">Sphinx</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/sphinx-bootstrap-theme/">Sphinx bootstrap theme</a></li>
</ul>
<p>These are bundled with the Python distrbution on Windows but other platforms will need to install them following the installation instructions <a class="reference external" href="https://github.com/mantidproject/mantid/blob/master/docs/README.md">here</a>. It is recommended that <code class="docutils literal"><span class="pre">pip</span></code> is used over <code class="docutils literal"><span class="pre">easy_install</span></code>.</p>
</div>
<div class="section" id="latex">
<h3><a class="toc-backref" href="#id4">LaTeX</a><a class="headerlink" href="#latex" title="Permalink to this headline">¶</a></h3>
<p>To view the equations built with the documentation you will need an installation of LaTeX on your system.</p>
<div class="section" id="linux">
<h4><a class="toc-backref" href="#id5">Linux</a><a class="headerlink" href="#linux" title="Permalink to this headline">¶</a></h4>
<p>If you have installed the mantid-develop package then you should have a working latex distribution. If not, use your package manager and search for a suitable candidate, most likely named something like <code class="docutils literal"><span class="pre">texlive</span></code>.</p>
</div>
<div class="section" id="macos">
<h4><a class="toc-backref" href="#id6">MacOS</a><a class="headerlink" href="#macos" title="Permalink to this headline">¶</a></h4>
<p>See <a class="reference external" href="http://tug.org/mactex/">here</a> for instructions on installing <code class="docutils literal"><span class="pre">MacTeX</span></code>.</p>
</div>
<div class="section" id="windows">
<h4><a class="toc-backref" href="#id7">Windows</a><a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h4>
<p>Download and install <code class="docutils literal"><span class="pre">MikTeX</span></code> from <a class="reference external" href="https://miktex.org/download">here</a>.</p>
<p>During installation there will be a question with a drop-down box relating to installing packages on demand - make sure “Ask first” is selected.</p>
<p>The first build of one of the <code class="docutils literal"><span class="pre">docs-*</span></code> targets after <code class="docutils literal"><span class="pre">MikTeX</span></code> has installed will raise a dialog, similar to this asking you if it is okay to install a package. For developers behind a proxy you will need to click on the “Change” button and enter the proxy information and select a new download location on the set of dialogs that appear before returning back to the main dialog. Check the box saying don’t ask again and click install.</p>
</div>
</div>
</div>
<div class="section" id="rest-editors-ide-plugins">
<h2><a class="toc-backref" href="#id8">reST editors/IDE plugins</a><a class="headerlink" href="#rest-editors-ide-plugins" title="Permalink to this headline">¶</a></h2>
<p>Several free & proprietary editors support syntax-highlighting reST. A list of the most notable ones can be found <a class="reference external" href="https://stackoverflow.com/questions/2746692/restructuredtext-tool-support">here</a>.</p>
<div class="section" id="restview">
<h3><a class="toc-backref" href="#id9">Restview</a><a class="headerlink" href="#restview" title="Permalink to this headline">¶</a></h3>
<p>A really handy tool whilst writing out .rst files is <a class="reference external" href="https://pypi.python.org/pypi/restview">restview</a> which can be easily installed using <code class="docutils literal"><span class="pre">pip</span></code>. It opens a webpage with the rst file processed and refreshes the page automatically whenever the .rst file is saved. This can help you quickly track down that unexpected space or missing newline without having to rebuild the documentation each time. It does not support sphinx directives so links will produce errors on the page which need to be checked by building the documentation using Mantid. The syntax to use it is:</p>
<p><code class="docutils literal"><span class="pre">restview</span> <span class="pre">path/to/file.rst</span></code></p>
</div>
</div>
<div class="section" id="the-restructuredtext-file">
<h2><a class="toc-backref" href="#id10">The reStructuredText File</a><a class="headerlink" href="#the-restructuredtext-file" title="Permalink to this headline">¶</a></h2>
<p><a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> is a markup format and is converted into themed html pages using Sphinx. A primer on reStructuredText can be found here along with a single-page cheat sheet.</p>
<p>The source files are .rst files which are located in the <code class="docutils literal"><span class="pre">docs/source</span></code> directory in the repository. There are various subdirectories based on the type of object being documented, i.e. <code class="docutils literal"><span class="pre">docs/source/algorithms</span></code>, <code class="docutils literal"><span class="pre">docs/source/functions</span></code>.</p>
<p>The documentation pages is aimed at <em>users</em>, not developers, and all information should be targeted for the users. Information for developers should go into doxygen/code-comments in the code or into <code class="docutils literal"><span class="pre">dev-docs</span></code>.</p>
<div class="section" id="directives">
<h3><a class="toc-backref" href="#id11">Directives</a><a class="headerlink" href="#directives" title="Permalink to this headline">¶</a></h3>
<p>Sphinx is built on the <code class="docutils literal"><span class="pre">docutils</span></code> package that allows for directives to be inserted in to reST comments. For example:</p>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">warning</span><span class="p">::</span>
This text will show up surrounded by a coloured box.
</pre></div>
</div>
<p>tells sphinx to treat the the given text differently and flag it so that a user will see it as a warning. The name of the directive is <code class="docutils literal"><span class="pre">warning</span></code> and the <code class="docutils literal"><span class="pre">..</span></code> is a reST comment syntax. The directive name must be followed by <code class="docutils literal"><span class="pre">::</span></code> so that Sphinx process knows it has a directive command and not just plain text. For a list of directives known to Sphinx, see <a class="reference external" href="http://www.sphinx-doc.org/en/master/rest.html#directives">here</a>.</p>
</div>
<div class="section" id="comments">
<h3><a class="toc-backref" href="#id12">Comments</a><a class="headerlink" href="#comments" title="Permalink to this headline">¶</a></h3>
<p>If you wish to place comments in the reST file that will not be rendered anywhere then start the line/block with <code class="docutils literal"><span class="pre">..</span></code>. See <a class="reference external" href="http://sphinx-doc.org/rest.html#comments">here</a> for more details.</p>
</div>
<div class="section" id="algorithms">
<h3><a class="toc-backref" href="#id13">Algorithms</a><a class="headerlink" href="#algorithms" title="Permalink to this headline">¶</a></h3>
<p>The algorithm documentation has a slightly more rigid structure and is described in more detail <a class="reference external" href="AlgorithmDocumentation.html">here</a> and <a class="reference external" href="AlgorithmUsageExamples.html">here</a>.</p>
</div>
<div class="section" id="interfaces">
<h3><a class="toc-backref" href="#id14">Interfaces</a><a class="headerlink" href="#interfaces" title="Permalink to this headline">¶</a></h3>
<p>For documenting custom interfaces, it is recommended that you consult <a class="reference external" href="InterfaceDocumentation.html">this</a> page, which explains how to document them, and which directives may be used in more detail.</p>
</div>
<div class="section" id="how-to-define-titles-sections-etc">
<h3><a class="toc-backref" href="#id15">How to define titles, sections etc.</a><a class="headerlink" href="#how-to-define-titles-sections-etc" title="Permalink to this headline">¶</a></h3>
<p>The syntax for headers in restructuredText is the header followed by a line containing symbols such as hyphens. It is possible to use different punctuation to create headers but within the Mantid .rst files we standardize on the characters used as follows:</p>
<dl class="docutils">
<dt>The title of the page</dt>
<dd>Should be the first header of your .rst file, and generally only occur once. (This is done for you in an algorithm with the <code class="docutils literal"><span class="pre">..</span> <span class="pre">algorithm::</span></code> directive)</dd>
</dl>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="gh">=============================================</span>
<span class="gh">Page title (e.g. Workspace) - This outputs H1</span>
<span class="gh">=============================================</span>
</pre></div>
</div>
<dl class="docutils">
<dt>Section headings</dt>
<dd>Sections, such as the description of an algorithm, can be created with the following syntax</dd>
</dl>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="gh"># Description - This outputs H2</span>
<span class="gh">-------------------------------</span>
</pre></div>
</div>
<dl class="docutils">
<dt>Sub-sections</dt>
<dd>The following is used to create a sub-section of the above section. This must follow after the above to be parsed correctly.</dd>
</dl>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="gh">Sub-heading - This outputs h3</span>
<span class="gh">#############################</span>
</pre></div>
</div>
<dl class="docutils">
<dt>Sub-sub-sections</dt>
<dd>The following is used to create a sub-header for the sub-heading above. This must also follow after the above header to be parsed correctly.</dd>
</dl>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="gh">Sub-sub-heading - Outputs h4</span>
<span class="gh">^^^^^^^^^^^^^^^^^^^^^^^^^^^^</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="things-to-avoid">
<h2><a class="toc-backref" href="#id16">Things to Avoid</a><a class="headerlink" href="#things-to-avoid" title="Permalink to this headline">¶</a></h2>
<p>If you have weird messages about sphinx warnings that happen on “Console output”, those are coming either from summary functions in algorithms or from parameter descriptions. In these</p>
<ul class="simple">
<li><em>Do not</em> use <code class="docutils literal"><span class="pre">*</span></code> in parameter names or summary. This yields “Inline emphasis start-string without end-string” warnings.</li>
<li><em>Do not</em> use things like <code class="docutils literal"><span class="pre">|Q|</span></code>. This yields sphinx error “Undefined substitution referenced”.</li>
<li><dl class="first docutils">
<dt>When using hyperlinks with a label, try to use anonymous hyperlinks (two underscores instead of one) to avoid name clashes.</dt>
<dd><ul class="first last">
<li><code class="docutils literal"><span class="pre">`MD</span> <span class="pre"><http://mysite.com/MD1.html>`__</span></code> and <code class="docutils literal"><span class="pre">`MD</span> <span class="pre"><http://mysite.com/MD2.html>`__</span></code> instead of <code class="docutils literal"><span class="pre">`MD</span> <span class="pre"><http://mysite.com/MD1.html>`_</span></code> and <code class="docutils literal"><span class="pre">`MD</span> <span class="pre"><http://mysite.com/MD2.html>`_</span></code>. The second on will result in a warning.</li>
</ul>
</dd>
</dl>
</li>
</ul>
<div class="section" id="common-warnings-and-fixes">
<h3><a class="toc-backref" href="#id17">Common Warnings and Fixes</a><a class="headerlink" href="#common-warnings-and-fixes" title="Permalink to this headline">¶</a></h3>
<p>While building the final output, Sphinx will emit warning messages if it things the input restructured text is malformed. This section lists some more common warnings along with suggestions for fixes.</p>
<div class="section" id="explicit-markup-ends-without-a-blank-line-unexpected-unindent">
<h4><a class="toc-backref" href="#id18">Explicit markup ends without a blank line; unexpected unindent.</a><a class="headerlink" href="#explicit-markup-ends-without-a-blank-line-unexpected-unindent" title="Permalink to this headline">¶</a></h4>
<p>This is caused by the lack of a blank line between an indented explicit markup block and more unindented text, e.g.</p>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">testcode</span><span class="p">::</span> ExHist
print "This is a test"
Output: <------------- There should be a blank line above this
<span class="p"> ..</span> <span class="ow">testoutput</span><span class="p">::</span> ExHist
</pre></div>
</div>
<p>It can be fixed by having a blank line between the indented block and the unindented text.</p>
</div>
<div class="section" id="inline-interpreted-text-or-phrase-reference-start-string-without-end-string">
<h4><a class="toc-backref" href="#id19">Inline interpreted text or phrase reference start-string without end-string</a><a class="headerlink" href="#inline-interpreted-text-or-phrase-reference-start-string-without-end-string" title="Permalink to this headline">¶</a></h4>
<p>This is caused by using one of the <a class="reference external" href="http://www.sphinx-doc.org/en/master/rest.html#inline-markup">inline markup tags</a>, where the text being wrapped splits over multiple lines. In these cases the directive variant of the inline markup should be used. One example is the <code class="docutils literal"><span class="pre">:math:</span></code> tag being spread over multiple lines. The tag <code class="docutils literal"><span class="pre">:math:</span></code> must only be used for inline markup, i.e. when there is no newline in the math string. For multi-line maths markup you must use the <code class="docutils literal"><span class="pre">..</span> <span class="pre">math::</span></code> directive instead.</p>
<div class="highlight-rest"><div class="highlight"><pre><span></span>:math:`\rm U \rm B \left(
\begin{array}{c}
h_i \\
k_i \\
l_i \\
\end{array}
\right) = \rm Q_{gon,i}` (1)
</pre></div>
</div>
<p>should be written</p>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">math</span><span class="p">::</span>
<------------------ intentional blank line
\rm U \rm B \left(
\begin{array}{c}
h_i \\
k_i \\
l_i \\
\end{array}
\right) = \rm Q_{gon,i} (1)
<------------------ intentional blank line
</pre></div>
</div>
<p>where there is an explicit blank line after the final line of latex. See <a class="reference external" href="http://sphinx-doc.org/ext/math.html">here</a> for more information.</p>
</div>
<div class="section" id="image-file-not-readable">
<h4><a class="toc-backref" href="#id20">image file not readable</a><a class="headerlink" href="#image-file-not-readable" title="Permalink to this headline">¶</a></h4>
<p>This indicates the that image referenced by <code class="docutils literal"><span class="pre">..</span> <span class="pre">image::</span></code> or <code class="docutils literal"><span class="pre">..</span> <span class="pre">figure::</span></code> cannot be accessed. Either the image is not there or the reference is incorrect.</p>
<p>Image links in Sphinx are either relative, in which case it is relative to the current document or absolute in which case the path is assumed relative to the root of the source tree (the directory containing the conf.py)</p>
</div>
<div class="section" id="unknown-directive-type-foo">
<h4><a class="toc-backref" href="#id21">Unknown directive type “foo”</a><a class="headerlink" href="#unknown-directive-type-foo" title="Permalink to this headline">¶</a></h4>
<p>Sphinx has encountered a line starting with <code class="docutils literal"><span class="pre">..</span> <span class="pre">foo::</span></code>, where <code class="docutils literal"><span class="pre">foo</span></code> is expected to be a known directive.</p>
<p>The fix is to correct the name of the directive.</p>
</div>
<div class="section" id="warnings-on-console-in-the-build-servers">
<h4><a class="toc-backref" href="#id22">Warnings on console (in the build servers)</a><a class="headerlink" href="#warnings-on-console-in-the-build-servers" title="Permalink to this headline">¶</a></h4>
<p>These type of errors occur in the summary function and/or in documentation of parameters in the init function. See <a class="reference internal" href="#things-to-avoid">Things to Avoid</a>.</p>
</div>
</div>
</div>
<div class="section" id="running-documentation-tests-locally">
<h2><a class="toc-backref" href="#id23">Running documentation tests locally</a><a class="headerlink" href="#running-documentation-tests-locally" title="Permalink to this headline">¶</a></h2>
<p>The usage tests are executed using a driver script, <code class="docutils literal"><span class="pre">runsphinx_doctest.py</span></code>, that is generated by CMake in the <code class="docutils literal"><span class="pre">docs</span></code> directory. A top-level target, <code class="docutils literal"><span class="pre">docs-test</span></code>, is created for each generator that invokes the script without any arguments and subsequently executes all of the available usage tests.</p>
<p>The driver script has been written to accept additional arguments in order to be able to limit the number of tests that are executed. To run a subset of the available tests, the script must be called manually and supplied with the <code class="docutils literal"><span class="pre">-R</span> <span class="pre">TESTREGEX</span></code> argument. The regex is applied to the filename of the document and will match anywhere within the name. The script can be called using either a plain Python interpreter or the MantidPlot executable. If using a plain Python interpreter then you will need to either have your <code class="docutils literal"><span class="pre">PYTHONPATH</span></code> set to find the <code class="docutils literal"><span class="pre">mantid</span></code> module or you can provide the <code class="docutils literal"><span class="pre">-m</span> <span class="pre">MANTIDPATH</span></code> option to have the script find the module for you.</p>
<p>It is recommended that the tests are run with MantidPlot as this is the easiest way to be sure that they are being run with the current build copy. As an example, to run any files that have Rebin in the filename you would type (assuming you are in the build directory):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="nb">bin</span><span class="o">/</span><span class="n">MantidPlot</span> <span class="o">-</span><span class="n">xq</span> <span class="n">docs</span><span class="o">/</span><span class="n">runsphinx_doctest</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">R</span> <span class="n">Rebin</span>
</pre></div>
</div>
<p>or with vanilla python</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>python docs/runsphinx_doctest.py -m $PWD/bin -R Rebin
</pre></div>
</div>
<p>For multi-configuration generators such as Visual Studio or XCode you will need to pick the configuration by choosing the apporiate directory, e.g. for MSVC debug (remembering that the slashes need to be backslash and not forward slash):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="nb">bin</span>\<span class="n">Debug</span>\<span class="n">MantidPlot</span> <span class="o">-</span><span class="n">xq</span> <span class="n">docs</span>\<span class="n">runsphinx_doctest</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">R</span> <span class="n">Rebin</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<ul class="nav navbar-nav" style=" float: right;">
<li><a href="#">Back to top</a></li>
</ul>
<p>
</p>
</div>
</footer>
</body>
</html>