From ff31c65fbe333d05c7984e8c8da6d38a7bbb5384 Mon Sep 17 00:00:00 2001
From: Antti Soininen <soininen@ill.fr>
Date: Wed, 21 Mar 2018 10:37:31 +0100
Subject: [PATCH] dev-docs: general, algorithm and interface documentation
guides.
Re #22082
---
dev-docs/source/AlgorithmDocumentation.rst | 194 ++++++++++++++
dev-docs/source/AlgorithmUsageExamples.rst | 224 ++++++++++++++++
dev-docs/source/DocumentationGuideForDevs.rst | 249 ++++++++++++++++++
dev-docs/source/FlowchartCreation.rst | 65 +++++
dev-docs/source/InterfaceDocumentation.rst | 53 ++++
5 files changed, 785 insertions(+)
create mode 100644 dev-docs/source/AlgorithmDocumentation.rst
create mode 100644 dev-docs/source/AlgorithmUsageExamples.rst
create mode 100644 dev-docs/source/DocumentationGuideForDevs.rst
create mode 100644 dev-docs/source/FlowchartCreation.rst
create mode 100644 dev-docs/source/InterfaceDocumentation.rst
diff --git a/dev-docs/source/AlgorithmDocumentation.rst b/dev-docs/source/AlgorithmDocumentation.rst
new file mode 100644
index 00000000000..dc03d48a52c
--- /dev/null
+++ b/dev-docs/source/AlgorithmDocumentation.rst
@@ -0,0 +1,194 @@
+.. _AlgorithmDocumentation:
+
+=======================
+Algorithm Documentation
+=======================
+
+.. contents::
+ :local:
+
+Summary
+=======
+
+This page deals with the specifics of how to document an algorithm. For a more general guide to the Mantid documentation system see `Documentation Guide For Devs <DocumentationGuideForDevs.html>`__.
+
+How to Document an Algorithm
+============================
+
+Algorithm documentation is stored in two places.
+
+* The code (.cpp / .h / .py) files: For strings that are needed in the GUI for tooltips etc.
+* The .rst file: For all other documentation, including the algorithm description and `usage examples <AlgorithmUsageExamples.html>`__.
+
+The Code Files
+--------------
+
+The code files hold documentation in two important areas.
+
+The ``summary`` method
+ The summary method should return a string (in plain text) that describes in a short sentence the purpose of the algorithm. This is used to provide a summary in the algorithm dialog box and in the algorithm documentation web page.
+
+In C++: (This example uses the .h file, you could of course implement it in the .cpp file)
+
+.. code-block:: c++
+
+ /// Algorithm's name for identification overriding a virtual method
+ const std::string name() const override { return "Rebin";}
+
+ ///Summary of algorithms purpose
+ const std::string summary() const override {return "Rebins data with new X bin boundaries.";}
+
+Property Descriptions
+---------------------
+
+Each property declaration in the init method of the .cpp file should include a description. This is used as a tooltip, and in the 'properties' table on the algorithm's documentation web page.
+
+.. note::
+
+ The tooltip may only show the description up to the first dot. Be sure that the first sentence in the description gives enough information to understand the purpose of the property.
+
+For example:
+
+.. code-block:: c++
+
+ declareProperty(
+ new WorkspaceProperty<>("InputWorkspace", "", Direction::Input),
+ "Workspace containing the input data");
+ declareProperty(
+ new WorkspaceProperty<>("OutputWorkspace","",Direction::Output),
+ "The name to give the output workspace");
+ declareProperty(
+ new ArrayProperty<double>("Params", boost::make_shared<RebinParamsValidator>()),
+ "A comma separated list of first bin boundary, width, last bin boundary. Optionally "
+ "this can be followed by a comma and more widths and last boundary pairs. "
+ "Optionally this can also be a single number, which is the bin width. "
+ "In this case, the boundary of binning will be determined by minimum and maximum TOF "
+ "values among all events, or previous binning boundary, in case of event Workspace, or "
+ "non-event Workspace, respectively. Negative width values indicate logarithmic binning. ");
+
+Workflow algorithms
+===================
+
+There should be a flow chart for workflow algorithms. See `here <FlowchartCreation.html>`__ on how to make one.
+
+Algorithm Directives
+====================
+
+We have defined several custom directives using the Sphinx extension framework. These are defined to generate the information from an algorithm that is not required to be hand written, i.e the properties table. Each .rst file that is documenting an algorithm should use these directives.
+
+As the **Description** and **Usage** of an algorithm *cannot* be obtained automatically, it must be manually entered. The structure of an algorithm's .rst is:
+
+.. code-block:: rest
+
+ .. algorithm::
+
+ .. summary::
+
+ .. alias::
+
+ .. properties::
+
+ Description
+ -----------
+
+ The description of your algorithm here.
+
+ Usage
+ -----
+
+ A custom usage example.
+
+ .. categories::
+
+ .. sourcelink::
+
+``.. algorithm ::``
+ This directive has several pieces of functionality, which includes:
+
+* A referable link is created for the algorithm. This allows other documentation pages create references to it (e.g. create links to it).
+* Insertion of the page title (which is the name of the algorithm, including the version).
+* Insertion of a screenshot of the algorithm's dialog.
+* Insertion of the Table Of Contents.
+
+``.. summary::``
+ The content of the summary method declared in your algorithm is output as HTML, for example, the following method is used in Rebin:
+
+.. code-block:: c++
+
+ /// Summary of algorithms purpose
+ const std::string summary() const override {
+ return "Rebins data with new X bin boundaries. For EventWorkspaces, you can very quickly rebin in-place by keeping the same output name and PreserveEvents=true.";
+ }
+
+``.. alias::``
+ This directive obtains aliases from the required ``alias`` method in the algorithm, for example, the following method is used in Rebin:
+
+.. code-block:: c++
+
+ /// Algorithm's aliases
+ const std::string alias() const override { return "rebin"; }
+
+``.. properties::``
+ As mentioned above, it is *critical* that you include a description for the properties of your algorithm. This directive obtains all of the algorithm's properties (set inside the algorithm's ``init`` method) and outputs in a table format.
+
+``.. categories::``
+ By default, this directive obtains the categories that were set in the ``categories`` method the algorithm. For example, in Rebin the category method is in the header and contains:
+
+.. code-block:: c++
+
+ /// Algorithm's category for identification
+ const std::string category() const override {return "Transforms\\Rebin";}
+
+When the HTML is generate a categories list is built that contains: Algorithms, Transforms and Rebin.
+
+It is possible to add additional categories by passing the directive arguments, for example, the following would output the above categories, and also `Example`:
+
+.. code-block: rest
+
+ .. categories:: Algorithms, Transforms, Rebin, Example
+
+``..sourcelink ::``
+ This directive adds links to the algorithms source code.
+
+Description
+===========
+
+This section must be manually entered. The description is an extension of the summary, and must contain a detailed overview of the algorithm's functionality.
+
+Referencing Other Algorithms
+----------------------------
+
+Every algorithm and version has been marked with a tag that can be used to reference it from other documents. If you need to reference the latest version of an algorithm, e.g. DiffractionFocussing, then in Sphinx you type would type
+
+.. code-block:: rest
+
+ :ref:`DiffractionFocussing <algm-DiffractionFocussing>`
+
+If you need to reference a particular version then you would type
+
+.. code-block:: rest
+
+ :ref:`DiffractionFocussing version 2 <algm-DiffractionFocussing-v2>`
+
+where the first part outside the angle brackets defines the link text and the part inside the angle brackets references the tag name.
+
+Usage
+=====
+
+This section *must* be manually entered. The usage is a 'code' example of the algorithm in use. The `testcode` directive must be used to verify the usage code you entered works correctly. See `here <AlgorithmUsageExamples>`__ for more information on how to write usage examples.
+
+Building the Documentation
+==========================
+
+One can update the documentation for a particular algorithm after changes have been introduced into the corresponding documentation file. Assuming you are in the build directory and want to update the documentation for Rebin:
+
+::
+
+ bin/MantidPlot -xq docs/runsphinx_html.py -R Rebin # builds HTML documentation
+ bin/MantidPlot -xq docs/runsphinx_qthelp.py -R Rebin # builds Qt-help documentation
+
+or with vanilla python
+
+::
+
+ python docs/runsphinx_html.py -m $PWD/bin -R Rebin
diff --git a/dev-docs/source/AlgorithmUsageExamples.rst b/dev-docs/source/AlgorithmUsageExamples.rst
new file mode 100644
index 00000000000..3c8ee85ebc3
--- /dev/null
+++ b/dev-docs/source/AlgorithmUsageExamples.rst
@@ -0,0 +1,224 @@
+.. _AlgorithmUsageExamples:
+
+========================
+Algorithm Usage Examples
+========================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+A *usage example* is part of the documentation page of an algorithm.
+
+From a user's point of view, the main purposes of usage examples are:
+
+* Getting started using the algorithm as part of a Python script
+* Understanding the algorithm
+* Showing hints/comments etc. that help understand Mantid Python scripting in general
+
+The usage examples are written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`__, which can be converted to HTML and the code in the usage examples can be tested. The image below demonstrates an example of converting reStructuredText to HTML.
+
+Guide
+=====
+
+The example below show the proposed way to format an usage example in reStructuredText.
+
+.. code-block:: rest
+
+ Usage
+ -----
+
+ **Example - simple rebin of a histogram workspace:**
+
+ .. testcode:: ExHistSimple
+
+ # create histogram workspace
+ dataX = [0,1,2,3,4,5,6,7,8,9] # or use dataX=range(0,10)
+ dataY = [1,1,1,1,1,1,1,1,1] # or use dataY=[1]*9
+ ws = CreateWorkspace(dataX, dataY)
+
+ # rebin from min to max with size bin = 2
+ ws = Rebin(ws, 2)
+
+ print "The rebinned X values are: " + str(ws.readX(0))
+ print "The rebinned Y values are: " + str(ws.readY(0))
+
+
+ Output:
+
+ .. testoutput:: ExHistSimple
+
+ The rebinned X values are: [ 0. 2. 4. 6. 8. 9.]
+ The rebinned Y values are: [ 2. 2. 2. 2. 1.]
+
+What is required is:
+
+* Short description explaining the example, formatted as shown above, i.e. using ``**`` to embolden the text.
+* A ``.. testcode::`` section, with a unique 'namespace' name, here ``ExHistSimple``. This 'namespace' is not shown when converted to HTML, but is used in testing the code. This section contains the actual Python code demonstrating a usage of the algorithm. This code block contains commented code, finishing with one or more Python ``print`` lines as shown
+* A ``.. testoutput::`` section. This section must have a matching 'namespace' name to the ``..testcode::`` section. It simply contains a copy of the text that is printed out in the ``..testcode::`` section.
+* Include the "Output:" string above the ``..testoutput::`` directive.
+
+What is optional:
+
+* A ``..testcleanup::`` section. This section must have a matching 'namespace' name to the ``..testcode::`` section. Here, add Python code to do any cleanup of files etc. that were created by the tests. See the notes below for things that are cleaned automatically.
+
+Notes:
+
+* The configuration has a global "testcleanup" implemented which calls ``FrameworkManager::clear()`` to clear algorithms, workspaces & instruments so these are dealt with automatically.
+* There must be a clear blank line before the ``.. testcode::`` and ``.. testoutput`` directives or the test is ignored. As with unit tests you should write a failing test first to ensure it is running.
+
+What is worth keeping in mind is:
+
+* *Assume the user is new to Python*. Consider giving hints to more advanced Python in comments, or introduce a simple example first.
+* Use comments.
+* Use Python ``print`` to output results, which, where possible, helps to understand the algorithm.
+
+A Jenkins job tests that the usage examples are not broken, i.e. that they continue to provide a working demonstration against the current build. It is vital to stress that the purpose of usage testing is *not to replace unit testing* (or system testing). The purpose of usage testing (better described as demonstration examples), is to provide some happy-path examples, which, where this is possible, can assist the user understanding of the Python code. This is very different from the purposes of testing in general, see `here <UnitTestGoodPractice.html>`__.
+
+Additional benefits of usage examples:
+
+* Quick look-up for developers on how to use a certain algorithm in Python scripting
+* Allow the user to test that scripts return expected output in their installed Mantid versions
+* Additional test coverage of Mantid Python API
+
+Using CreateSampleWorkspace and CreateWorkspace
+-----------------------------------------------
+
+There are many ways to create sample workspaces. For example :ref:`CreateMDHistoWorkspace <algm-CreateMDHistoWorkspace>`, :ref:`CreateSampleWorkspace <algm-CreateSampleWorkspace>` and :ref:`CreateWorkspace <algm-CreateWorkspace>`. CreateSampleWorkspace creates a fully defined workspace (either event or histogram) but for creating simple histogram workspace CreateWorkspace may be a better option. Above is shown an example where CreateWorkspace is used. Below is a more complex use of CreateSampleWorkspace:
+
+.. code-block:: rest
+
+ Usage
+ -----
+
+ **Example - Fit a Gaussian to a peak in a spectrum:**
+
+ .. testcode:: ExFitPeak
+
+ # create a workspace with a gaussian peak sitting on top of a linear (here flat) background
+ ws = CreateSampleWorkspace(Function="User Defined", UserDefinedFunction="name=LinearBackground, \
+ A0=0.3;name=Gaussian, PeakCentre=5, Height=10, Sigma=0.7", NumBanks=1, BankPixelWidth=1, XMin=0, XMax=10, BinWidth=0.1)
+
+ # Setup the data to fit:
+ workspaceIndex = 0 # the spectrum with which WorkspaceIndex to fit
+ startX = 1 # specify fitting region
+ endX = 9 #
+
+ # Setup the model, here a Gaussian, to fit to data
+ tryCentre = '4' # A start guess on peak centre
+ sigma = '1' # A start guess on peak width
+ height = '8' # A start guess on peak height
+ myFunc = 'name=Gaussian, Height='+height+', PeakCentre='+tryCentre+', Sigma='+sigma
+ # here purposely haven't included a linear background which mean fit will not be spot on
+ # to include a linear background uncomment the line below
+ #myFunc = 'name=LinearBackground, A0=0.3;name=Gaussian, Height='+height+', PeakCentre='+tryCentre+', Sigma='+sigma
+
+ # Do the fitting
+ fitStatus, chiSq, covarianceTable, paramTable, fitWorkspace = Fit(InputWorkspace='ws', \
+ WorkspaceIndex=0, StartX = startX, EndX=endX, Output='fit', Function=myFunc)
+
+ print "The fit was: " + fitStatus
+ print("chi-squared of fit is: %.2f" % chiSq)
+ print("Fitted Height value is: %.2f" % paramTable.column(1)[0])
+ print("Fitted centre value is: %.2f" % paramTable.column(1)[1])
+ print("Fitted sigma value is: %.2f" % paramTable.column(1)[2])
+ # fitWorkspace contains the data, the calculated and the difference patterns
+ print "Number of spectra in fitWorkspace is: " + str(fitWorkspace.getNumberHistograms())
+ print("The 20th y-value of the calculated pattern: %.4f" % fitWorkspace.readY(1)[19])
+
+ .. testcleanup:: ExFitPeak
+
+ DeleteWorkspace(ws)
+
+ Output:
+
+ .. testoutput:: ExFitPeak
+
+ The fit was: success
+ chi-squared of fit is: 0.14
+ Fitted Height value is: 9.79
+ Fitted centre value is: 5.05
+ Fitted sigma value is: 0.77
+ Number of spectra in fitWorkspace is: 3
+ The 20th y-value of the calculated pattern: 0.2361
+
+For a more simple use of CreateSampleWorkspace see example below (note if no arguments are given then a histogram workspace is created):
+
+.. code-block:: rest
+
+ Usage
+ -----
+
+ **Example - use option PreserveEvents:**
+
+ .. testcode:: ExEventRebin
+
+ # create some event workspace
+ ws = CreateSampleWorkspace(WorkspaceType="Event")
+
+ print "What type is the workspace before 1st rebin: " + str(type(ws))
+ # rebin from min to max with size bin = 2 preserving event workspace (default behaviour)
+ ws = Rebin(ws, 2)
+ print "What type is the workspace after 1st rebin: " + str(type(ws))
+ ws = Rebin(ws, 2, PreserveEvents=False)
+ print "What type is the workspace after 2nd rebin: " + str(type(ws))
+ # note you can also check the type of a workspace using: print isinstance(ws, IEventWorkspace)
+
+ .. testcleanup:: ExEventRebin
+
+ DeleteWorkspace(ws)
+
+ Output:
+
+ .. testoutput:: ExEventRebin
+
+ What type is the workspace before 1st rebin: <class 'mantid.api._api.IEventWorkspace'>
+ What type is the workspace after 1st rebin: <class 'mantid.api._api.IEventWorkspace'>
+ What type is the workspace after 2nd rebin: <class 'mantid.api._api.MatrixWorkspace'>
+
+When needing to load a data file
+--------------------------------
+
+Instructions to add a new data file to the repository are available `here <DataFilesForTesting.html>`__. Files from the repository will be bundled up into a .zip file, and this .zip made available for download from the Mantid download page.
+
+If you use files you must add the line
+
+.. code-block:: rest
+
+ .. include:: ../usagedata-note.txt
+
+as shown in the example below. This will generate a note to the user explaining how to download the UsageData.
+
+.. code-block:: rest
+
+ Usage
+ -----
+
+ .. include:: ../usagedata-note.txt
+
+ **Example - Load ISIS histogram Nexus file:**
+ (see :ref:`LoadISISNexus <algm-LoadISISNexus>` for more options)
+
+ .. testcode:: ExLoadISISnexusHist
+
+ # Load ISIS LOQ histogram dataset
+ ws = Load('LOQ49886.nxs')
+
+ print "The 1st x-value of the first spectrum is: " + str(ws.readX(0)[0])
+
+ .. testcleanup:: ExLoadISISnexusHist
+
+ DeleteWorkspace(ws)
+
+ Output:
+
+ .. testoutput:: ExLoadISISnexusHist
+
+ The 1st x-value of the first spectrum is: 5.0
+
+Running the Tests
+=================
+
+See `here <DocumentationGuideForDevs.html>`__ for how to run and test the usage examples locally.
diff --git a/dev-docs/source/DocumentationGuideForDevs.rst b/dev-docs/source/DocumentationGuideForDevs.rst
new file mode 100644
index 00000000000..a022439e855
--- /dev/null
+++ b/dev-docs/source/DocumentationGuideForDevs.rst
@@ -0,0 +1,249 @@
+.. _DocumentationGuideForDevs:
+
+============================
+Documentation Guide for Devs
+============================
+
+.. contents::
+ :local:
+
+Rationale
+=========
+
+The algorithm documentation approach aims to:
+
+#. Keep .cpp files clean and easy to maintain.
+#. Make the documentation files easier to edit, supporting the use of external editors.
+#. Simplify the Mantid documentation workflow.
+
+To do this we have harmonised most of our documentation workflow to use sphinx, extended a bit by some Mantid custom tag extensions.
+
+Prerequisites
+=============
+
+The documentation build requires:
+
+Sphinx
+------
+
+* `Sphinx <http://www.sphinx-doc.org/en/master/>`__
+* `Sphinx bootstrap theme <https://pypi.python.org/pypi/sphinx-bootstrap-theme/>`__
+
+These are bundled with the Python distrbution on Windows but other platforms will need to install them following the installation instructions `here <https://github.com/mantidproject/mantid/blob/master/docs/README.md>`__. It is recommended that ``pip`` is used over ``easy_install``.
+
+LaTeX
+-----
+
+To view the equations built with the documentation you will need an installation of LaTeX on your system.
+
+Linux
+#####
+
+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 ``texlive``.
+
+MacOS
+#####
+
+See `here <http://tug.org/mactex/>`__ for instructions on installing ``MacTeX``.
+
+Windows
+#######
+
+Download and install ``MikTeX`` from `here <https://miktex.org/download>`__.
+
+During installation there will be a question with a drop-down box relating to installing packages on demand - make sure "Ask first" is selected.
+
+The first build of one of the ``docs-*`` targets after ``MikTeX`` 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.
+
+reST editors/IDE plugins
+========================
+
+Several free & proprietary editors support syntax-highlighting reST. A list of the most notable ones can be found `here <https://stackoverflow.com/questions/2746692/restructuredtext-tool-support>`__.
+
+Restview
+--------
+
+A really handy tool whilst writing out .rst files is `restview <https://pypi.python.org/pypi/restview>`__ which can be easily installed using ``pip``. 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:
+
+``restview path/to/file.rst``
+
+The reStructuredText File
+=========================
+
+`reStructuredText <http://docutils.sourceforge.net/rst.html>`__ 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.
+
+The source files are .rst files which are located in the ``docs/source`` directory in the repository. There are various subdirectories based on the type of object being documented, i.e. ``docs/source/algorithms``, ``docs/source/functions``.
+
+The documentation pages is aimed at *users*, 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 ``dev-docs``.
+
+Directives
+----------
+
+Sphinx is built on the ``docutils`` package that allows for directives to be inserted in to reST comments. For example:
+
+.. code-block:: rest
+
+ .. warning::
+ This text will show up surrounded by a coloured box.
+
+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 ``warning`` and the ``..`` is a reST comment syntax. The directive name must be followed by ``::`` so that Sphinx process knows it has a directive command and not just plain text. For a list of directives known to Sphinx, see `here <http://www.sphinx-doc.org/en/master/rest.html#directives>`__.
+
+Comments
+--------
+
+If you wish to place comments in the reST file that will not be rendered anywhere then start the line/block with ``..``. See `here <http://sphinx-doc.org/rest.html#comments>`__ for more details.
+
+Algorithms
+----------
+
+The algorithm documentation has a slightly more rigid structure and is described in more detail `here <AlgorithmDocumentation.html>`__ and `here <AlgorithmUsageExamples.html>`__.
+
+Interfaces
+----------
+
+For documenting custom interfaces, it is recommended that you consult `this <InterfaceDocumentation.html>`__ page, which explains how to document them, and which directives may be used in more detail.
+
+How to define titles, sections etc.
+-----------------------------------
+
+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:
+
+The title of the page
+ Should be the first header of your .rst file, and generally only occur once. (This is done for you in an algorithm with the ``.. algorithm::`` directive)
+
+.. code-block:: rest
+
+ =============================================
+ Page title (e.g. Workspace) - This outputs H1
+ =============================================
+
+Section headings
+ Sections, such as the description of an algorithm, can be created with the following syntax
+
+.. code-block:: rest
+
+ # Description - This outputs H2
+ -------------------------------
+
+Sub-sections
+ The following is used to create a sub-section of the above section. This must follow after the above to be parsed correctly.
+
+.. code-block:: rest
+
+ Sub-heading - This outputs h3
+ #############################
+
+Sub-sub-sections
+ 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.
+
+.. code-block:: rest
+
+ Sub-sub-heading - Outputs h4
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Things to Avoid
+===============
+
+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
+
+* *Do not* use ``*`` in parameter names or summary. This yields “Inline emphasis start-string without end-string†warnings.
+* *Do not* use things like ``|Q|``. This yields sphinx error “Undefined substitution referencedâ€.
+* When using hyperlinks with a label, try to use anonymous hyperlinks (two underscores instead of one) to avoid name clashes.
+ * ```MD <http://mysite.com/MD1.html>`__`` and ```MD <http://mysite.com/MD2.html>`__`` instead of ```MD <http://mysite.com/MD1.html>`_`` and ```MD <http://mysite.com/MD2.html>`_``. The second on will result in a warning.
+
+Common Warnings and Fixes
+-------------------------
+
+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.
+
+Explicit markup ends without a blank line; unexpected unindent.
+###############################################################
+
+This is caused by the lack of a blank line between an indented explicit markup block and more unindented text, e.g.
+
+.. code-block:: rest
+
+ .. testcode:: ExHist
+
+ print "This is a test"
+ Output: <------------- There should be a blank line above this
+
+ .. testoutput:: ExHist
+
+It can be fixed by having a blank line between the indented block and the unindented text.
+
+Inline interpreted text or phrase reference start-string without end-string
+###########################################################################
+
+This is caused by using one of the `inline markup tags <http://www.sphinx-doc.org/en/master/rest.html#inline-markup>`__, 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 ``:math:`` tag being spread over multiple lines. The tag ``:math:`` 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 ``.. math::`` directive instead.
+
+.. code-block:: rest
+
+ :math:`\rm U \rm B \left(
+ \begin{array}{c}
+ h_i \\
+ k_i \\
+ l_i \\
+ \end{array}
+ \right) = \rm Q_{gon,i}` (1)
+
+should be written
+
+.. code-block:: rest
+
+ .. math::
+ <------------------ 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
+
+where there is an explicit blank line after the final line of latex. See `here <http://sphinx-doc.org/ext/math.html>`__ for more information.
+
+image file not readable
+#######################
+
+This indicates the that image referenced by ``.. image::`` or ``.. figure::`` cannot be accessed. Either the image is not there or the reference is incorrect.
+
+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)
+
+Unknown directive type "foo"
+############################
+
+Sphinx has encountered a line starting with ``.. foo::``, where ``foo`` is expected to be a known directive.
+
+The fix is to correct the name of the directive.
+
+Warnings on console (in the build servers)
+##########################################
+
+These type of errors occur in the summary function and/or in documentation of parameters in the init function. See `Things to Avoid`_.
+
+Running documentation tests locally
+===================================
+
+The usage tests are executed using a driver script, ``runsphinx_doctest.py``, that is generated by CMake in the ``docs`` directory. A top-level target, ``docs-test``, is created for each generator that invokes the script without any arguments and subsequently executes all of the available usage tests.
+
+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 ``-R TESTREGEX`` 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 ``PYTHONPATH`` set to find the ``mantid`` module or you can provide the ``-m MANTIDPATH`` option to have the script find the module for you.
+
+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):
+
+::
+
+ bin/MantidPlot -xq docs/runsphinx_doctest.py -R Rebin
+
+or with vanilla python
+
+::
+
+ python docs/runsphinx_doctest.py -m $PWD/bin -R Rebin
+
+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):
+
+::
+
+ bin\Debug\MantidPlot -xq docs\runsphinx_doctest.py -R Rebin
diff --git a/dev-docs/source/FlowchartCreation.rst b/dev-docs/source/FlowchartCreation.rst
new file mode 100644
index 00000000000..8b1db35c64a
--- /dev/null
+++ b/dev-docs/source/FlowchartCreation.rst
@@ -0,0 +1,65 @@
+.. _FlowchartCreation:
+
+==================
+Flowchart Creation
+==================
+
+.. contents::
+ :local:
+
+
+The flowchart diagrams are created by writing ``graphviz`` .dot files that describe the diagram in plain text, and placing them into ``docs/source/diagrams``. These can then be rendered in documentation by using the diagram directive in an .rst file:
+
+.. code-block:: rest
+
+ .. diagram:: AlgorithmName-v1_wkflw.dot
+
+Examples of this can be found in `ReflectometryReductionOne1.rst <https://raw.githubusercontent.com/mantidproject/mantid/master/docs/source/algorithms/ReflectometryReductionOne-v1.rst>`__ and `ReflectometryReductionOneAuto-v1.rst <https://raw.githubusercontent.com/mantidproject/mantid/master/docs/source/algorithms/ReflectometryReductionOneAuto-v1.rst>`__.
+
+The .dot format is quite simple¸ but very powerful for describing graphs. The approach we use is to describe all the nodes (shapes) we want first, grouping them into their types, and then defining how they're connected.
+
+To provide a uniform look to all the workflow diagrams, templated keywords are provided which are swapped out with the correct styling options when the documentation is built. They are of the form ``${context}_style``. They're defined by the `diagram directive <https://raw.githubusercontent.com/mantidproject/mantid/master/docs/sphinxext/mantiddoc/directives/diagram.py>`__.
+
+An algorithm that takes one input workspace and scales it by a given parameter/property if it was given, may look like this:
+
+::
+
+ digraph DiagramName {
+ //Comments are inserted in the same way as C++
+ label = "MultiplyByParam Workflow Diagram"
+ $global_style
+
+ subgraph params {
+ //These keywords beginning with $ are replaced with commands to style all the nodes in the subgraph correctly
+ $param_style
+ inputWorkspace [label="InputWorkspace"]
+ outputWorkspace [label="OutputWorkspace"]
+ coefficient [label="Coefficient"]
+ }
+
+ subgraph decisions {
+ $decision_style
+ checkCoefficient [label="Was Coefficient\ngiven?"]
+ }
+
+ subgraph algorithms {
+ $algorithm_style
+ scale [label="Scale"]
+ }
+
+ //Define the connections, labelling some of them
+ inputWorkspace -> checkCoefficient
+ coefficient -> scale [label="Factor"]
+ checkCoefficient -> scale [label="Yes"]
+ checkCoefficient -> outputWorkspace [label="No"]
+ scale -> outputWorkspace
+ }
+
+While creating the diagrams it's inconvenient to recompile the documentation with each change, so you may want to render the graph manually. This can be achieved on linux or cygwin by running the following command. *You may need to comment out the "$foo_style" lines when manually rendering as they are not valid graphviz syntax* (you can do this on the fly using sed to avoid having to edit the file).
+
+::
+
+ dot -Tpng -o output_image.png input_file.dot # render a graph manually
+ sed 's/\$/\/\/$/g' input_file.dot | dot -Tpng -o output_image.png # excludes $foo_style lines
+
+You can also render them in a web browser using this `online graph renderer <http://www.webgraphviz.com/>`__.
diff --git a/dev-docs/source/InterfaceDocumentation.rst b/dev-docs/source/InterfaceDocumentation.rst
new file mode 100644
index 00000000000..1e49cbb60f0
--- /dev/null
+++ b/dev-docs/source/InterfaceDocumentation.rst
@@ -0,0 +1,53 @@
+.. _InterfaceDocumentation:
+
+=======================
+Interface Documentation
+=======================
+
+.. contents::
+ :local:
+
+Summary
+=======
+
+This page deals with the specifics of how to document Custom Interfaces. For a more general guide to the Mantid documentation system see `Documentation Guide For Devs <DocumentationGuideForDevs.html>`__.
+
+The ``interface`` Directive
+===========================
+
+This directive allows you to insert a screenshot of the interface into the documentation. It has one required argument: the name of the interface, as given by the interface's ``name()`` method. Several options, detailed below, may also be provided to further control the behaviour of this directive.
+
+The inserted screenshots are generated automatically when the documentation is being compiled. This is preferable to screenshots taken manually as these will automatically stay up to date.
+
+Options
+-------
+
+widget
+ You can give the name of a widget in the interface to only take a screenshot of that widget. If not given, a screenshot of the entire interface will be inserted.
+
+align
+ This specifies the alignment to use for the screenshot. Valid settings are *left*, *center*, and *right*. Defaults to *center*.
+
+Examples
+========
+
+This inserts a screenshot of the Muon Analysis interface:
+
+.. code-block:: rest
+
+ .. interface:: Muon Analysis
+
+This inserts a screenshot of the Muon Analysis interface's Grouping Options tab:
+
+.. code-block:: rest
+
+ .. interface:: Muon Analysis
+ :widget: GroupingOptions
+
+This inserts a screenshot of the main table in the ISIS Reflectometry custom interface, aligned to the right:
+
+.. code-block:: rest
+
+ .. interface:: ISIS Reflectometry
+ :widget: viewTable
+ :align: right
--
GitLab