Merge remote-tracking branch 'origin/feature/9521_sphinx_doc_directives'

Code/Mantid/Framework/API/inc/MantidAPI/AlgorithmFactory.h

@@ -125,6 +125,9 @@ public:
   /// Get the algorithm names and version - mangled use decodeName to separate
   const std::vector<std::string> getKeys() const;
   const std::vector<std::string> getKeys(bool includeHidden) const;
+
+  /// Returns the highest version of the algorithm currently registered
+  int highestVersion(const std::string & algorithmName) const;
   
   ///Get the algorithm categories
   const std::set<std::string> getCategories(bool includeHidden=false) const;

Code/Mantid/Framework/API/src/AlgorithmFactory.cpp

@@ -227,6 +227,21 @@ namespace Mantid
     }
   }
 
+  /**
+   * @param algorithmName The name of an algorithm registered with the factory
+   * @return An integer corresponding to the highest version registered
+   * @throw std::invalid_argument if the algorithm cannot be found
+   */
+  int AlgorithmFactoryImpl::highestVersion(const std::string &algorithmName) const
+  {
+    VersionMap::const_iterator viter = m_vmap.find(algorithmName);
+    if(viter != m_vmap.end()) return viter->second;
+    else
+    {
+      throw std::invalid_argument("AlgorithmFactory::highestVersion() - Unknown algorithm '" + algorithmName + "'");
+    }
+  }
+
 /**
   * Return the categories of the algorithms. This includes those within the Factory itself and 
   * any cleanly constructed algorithms stored here.

Code/Mantid/Framework/API/test/AlgorithmFactoryTest.h

@@ -106,6 +106,23 @@ public:
     TS_ASSERT_THROWS_NOTHING(keys = AlgorithmFactory::Instance().getKeys());
     TS_ASSERT_EQUALS(noOfAlgs - 1, keys.size());
   }
+
+  void test_HighestVersion()
+  {
+    auto & factory = AlgorithmFactory::Instance();
+
+    TS_ASSERT_THROWS(factory.highestVersion("ToyAlgorithm"), std::invalid_argument);
+
+    AlgorithmFactory::Instance().subscribe<ToyAlgorithm>();
+    TS_ASSERT_EQUALS(1, factory.highestVersion("ToyAlgorithm"));
+
+    Mantid::Kernel::Instantiator<ToyAlgorithmTwo, Algorithm>* newTwo = new Mantid::Kernel::Instantiator<ToyAlgorithmTwo, Algorithm>;
+    AlgorithmFactory::Instance().subscribe(newTwo);
+    TS_ASSERT_EQUALS(2, factory.highestVersion("ToyAlgorithm"));
+
+    AlgorithmFactory::Instance().unsubscribe("ToyAlgorithm",1);
+    AlgorithmFactory::Instance().unsubscribe("ToyAlgorithm",2);
+  }
   
   void testCreate()
   {
@@ -201,4 +218,4 @@ public:
 
 };
 
-#endif
\ No newline at end of file
+#endif

Code/Mantid/Framework/PythonInterface/mantid/api/src/Exports/AlgorithmFactory.cpp

@@ -112,7 +112,8 @@ void export_AlgorithmFactory()
                             "Returns true if the given algorithm exists with an option to specify the version"))
 
       .def("getRegisteredAlgorithms", &getRegisteredAlgorithms, "Returns a Python dictionary of currently registered algorithms")
-
+      .def("highestVersion", &AlgorithmFactoryImpl::highestVersion,
+           "Returns the highest version of the named algorithm. Throws ValueError if no algorithm can be found")
       .def("subscribe", &subscribe, "Register a Python class derived from PythonAlgorithm into the factory")
 
       .def("Instance", &AlgorithmFactory::Instance, return_value_policy<reference_existing_object>(),

Code/Mantid/MantidPlot/mantidplot.py

@@ -915,13 +915,17 @@ def screenshot_to_dir(widget, filename, screenshot_dir):
     @param filename :: Destination filename for that image
     @param screenshot_dir :: Directory to put the screenshots into.
     """
-        # Find the widget if handled with a proxy
+    # Find the widget if handled with a proxy
     if hasattr(widget, "_getHeldObject"):
         widget = widget._getHeldObject()
                 
     if widget is not None:
         camera = Screenshot()
-        threadsafe_call(camera.take_picture, widget, os.path.join(screenshot_dir, filename+".png"))
+        imgpath = os.path.join(screenshot_dir, filename)
+        threadsafe_call(camera.take_picture, widget, imgpath)
+        return imgpath
+    else:
+        raise RuntimeError("Unable to retrieve widget. Has it been deleted?")
     
 
 #=============================================================================

Code/Mantid/MantidPlot/test/MantidPlotAlgorithmDialogTest.py

@@ -23,10 +23,10 @@ class MantidPlotAlgorithmDialogTest(unittest.TestCase):
         interface_manager = mantidqtpython.MantidQt.API.InterfaceManager()
         dialog = threadsafe_call( interface_manager.createDialogFromName, self.__target_algorithm__, self.__clean_properties__)
         screenshotdir = tempfile.gettempdir();
-        file = "CreateMDWorkspace_screenshot"
-        screenshot_to_dir(widget=dialog, filename=file, screenshot_dir=screenshotdir)
+        filename = "CreateMDWorkspace_screenshot.png"
+        screenshot_to_dir(widget=dialog, filename=filename, screenshot_dir=screenshotdir)
         threadsafe_call(dialog.close)
-        file_abs = os.path.join(screenshotdir, file + ".png")
+        file_abs = os.path.join(screenshotdir, filename)
         file_exists = os.path.isfile(file_abs)
         self.assertEquals(file_exists, True, "Screenshot was not written out as expected.")
         if file_exists:

Code/Mantid/docs/CMakeLists.txt

+###############################################################################
+# Sphinx documentation
+###############################################################################
+find_package ( Sphinx )
+
+if ( SPHINX_FOUND )
+  # We generate a target per build type, i.e docs-html, docs-test
+  set ( SPHINX_BUILD_DIR ${CMAKE_BINARY_DIR}/docs )
+  set ( SCREENSHOTS_DIR ${SPHINX_BUILD_DIR}/screenshots )
+
+  # targets
+  set ( TARGET_PREFIX docs)
+  # runner - default=current build
+  set ( DOCS_RUNNER_EXE ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/${CMAKE_CFG_INTDIR}/MantidPlot CACHE FILEPATH 
+                        "MantidPlot executable to use to build the documentation" )
+
+  # HTML target
+  set ( BUILDER html )
+  configure_file ( runsphinx.py.in runsphinx_html.py @ONLY )
+  add_custom_target ( ${TARGET_PREFIX}-html
+    COMMAND ${DOCS_RUNNER_EXE} -xq runsphinx_html.py
+    COMMENT "Building html documentation"
+  )
+
+  # doctest target
+  set ( BUILDER doctest )
+  configure_file ( runsphinx.py.in runsphinx_doctest.py @ONLY )
+  add_custom_target ( ${TARGET_PREFIX}-test
+    COMMAND ${DOCS_RUNNER_EXE} -xq runsphinx_doctest.py
+    COMMENT "Running documentation tests"
+  )
+
+endif ()
+
+
+###############################################################################
+# QtAssistant
+###############################################################################
 if ( APPLE )
   set ( ENABLE_QTASSISTANT False CACHE BOOL "Build qt-assistant documentation" )
 else ()

Code/Mantid/docs/DocumentationStyleGuide.rst

+=========================
+Documentation Style Guide
+=========================
+
+This guide describes the formatting that should be followed when documenting Mantid functionality. The documentation is built using `Sphinx <http://sphinx.pocoo.org/>` and when using Sphinx most of what you type is reStructuredText. For more information on reStructeredText see:
+
+* https://pythonhosted.org/an_example_pypi_project/sphinx.html
+* http://docutils.sourceforge.net/rst.html
+* http://docutils.sourceforge.net/docs/user/rst/quickref.html
+* http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt
+

Code/Mantid/docs/README.md

+The Mantid documentation is written in [reStructuredText](http://docutils.sourceforge.net/rst.html) and processed using [Sphinx](http://sphinx.pocoo.org/). It uses a custom
+boostrap theme for Sphinx and both are required to build the documentation.
+
+To install Sphinx and the bootstrap theme use `easy_install`:
+
+    easy_install -U Sphinx
+    easy_install -U sphinx-bootstrap-theme
+
+or `pip`:
+
+    pip install Sphinx
+    pip install sphinx-bootstrap-theme
+
+This may require admin privileges on some environments.
+
+CMake produces a `docs-html` target that is used to build the documentation. The output files will appear in a `html` sub directory of the main `build/docs` directory.
\ No newline at end of file

Code/Mantid/docs/runsphinx.py.in

+"""We need to run Sphinx inside MantidPlot to document the internal
+   module. This script calls the sphinx entry point with the necessary 
+   arguments
+"""
+
+__requires__ = 'Sphinx'
+import sys
+import os
+from pkg_resources import load_entry_point
+
+mantidplot = "@CMAKE_RUNTIME_OUTPUT_DIRECTORY@/MantidPlot"
+builder = "@BUILDER@"
+src_dir = "@CMAKE_CURRENT_SOURCE_DIR@/source"
+screenshots_dir = "@SCREENSHOTS_DIR@"
+output_dir = os.path.join("@SPHINX_BUILD_DIR@", builder)
+
+# set environment
+os.environ["SCREENSHOTS_DIR"] = screenshots_dir
+# fake the sys args
+argv = [mantidplot,'-b', builder, src_dir, output_dir]
+if __name__ == '__main__':
+    sys.exit(
+      load_entry_point(__requires__, 'console_scripts', 'sphinx-build')(argv)
+    )
+

Code/Mantid/docs/source/_static/custom.css

+/*-------------------- $GENERAL --------------------*/
+
+#table-of-contents { border: none; }
+
+/*-------------------- $NAV --------------------*/
+
+.navbar-version { display: none; }
+
+/*-------------------- $LINKS --------------------*/
+
+a {
+  color: #009933;
+  text-decoration: none;
+}
+
+a:hover {
+  color: #009933;
+  text-decoration: underline;
+}
+
+/*-------------------- $SPACING --------------------*/
+
+body { font-size: 1.6em; } /* 16px */
+dl dd { margin: .5em 0 .5em 1.6em; }
+h1,h2 { margin-bottom: .5em; }
+
+/*-------------------- $IMAGES --------------------*/
+
+.figure {
+  border: 1px solid #CCC;
+  padding: 10px 10px 0 10px;
+  background-color: whiteSmoke;
+  text-align: center;
+  width: 300px;
+  float: right;
+}
+
+.screenshot {
+  height: 240px;
+  padding-bottom: 1em;
+}
+
+.figure { margin: 0; }
+
+/*-------------------- $TABLES --------------------*/
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1.6em 0;
+}
+
+/* Zebra striping */
+tr:nth-of-type(odd) { background: white; }
+
+tr:hover { background-color: whiteSmoke; }
+
+th {
+  background: #E0DFDE;
+  font-size: 1.3em;
+}
+
+td, th {
+  padding: .75em;
+  border: 1px solid #CCC;
+  text-align: left;
+}
+
+/*-------------------- $MEDIA-QUERIES --------------------*/
+
+@media (min-width: 1200px) {
+  #table-of-contents {
+    width: auto;
+    max-width: 40%;
+  }
+}

Code/Mantid/docs/source/_templates/category.html

+{# Generates a better view for category pages #}
+
+{% extends "layout.html" %}
+
+{% macro split_to_three_columns(item_list) -%}
+{# Split list into 3 columns #}
+{# Uses bootstrap col-md-4 for each column along with slice(3) to divide input list #}
+{# It currently assumes the items in the list are mantiddoc.directives.categories.PageRef classes #}
+    <div class="row">
+    {%- for column in item_list|slice(3) %}
+      <div class="col-md-4">
+      {%- set first = True %}
+      {%- for item in column %}
+        {%- if (item.name[0] != section or first) %}
+          {%- set section = item.name[0] %}
+          {%- if first != true %}
+            </ul>
+          {%- endif %}
+          <h3 style="font-weight:bold">{{ section }}</h3>
+          <ul>
+        {%- endif %}
+        <li><a href="{{ item.html_link() }}">{{ item.name }}</a></li>
+        {%- set first = False -%}
+      {%- endfor -%}
+      </ul>
+      </div>
+    {%- endfor -%}
+    </div>
+{%- endmacro %}
+
+{%- block body -%}
+    <h1> Category: {{ title }} </h1>
+    {% if subcategories %}
+    <br>
+    <h2> Subcategories </h2>
+    {{ split_to_three_columns(subcategories) }}
+    <hr>
+    {% endif %}
+
+    <h2> Pages </h2>
+    {{ split_to_three_columns(pages) }}
+
+{%- endblock -%}
\ No newline at end of file

Code/Mantid/docs/source/_templates/layout.html

+{% extends "!layout.html" %}
+
+{# Custom CSS overrides #}
+{% set bootswatch_css_custom = ['_static/custom.css'] %}

Code/Mantid/docs/source/_templates/navbar.html

+{% extends "!navbar.html" %}
+
+{%- block sidebarlogo %}
+{%- if logo -%}
+  <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo" width=113 height=24/></a>
+{%- endif %}
+{%- endblock -%}
+

Code/Mantid/docs/source/_templates/redirect.html

+<!DOCTYPE HTML>
+<html lang="en-US">
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="refresh" content="1;{{ target }}">
+    <script type="text/javascript">
+        window.location.href = "{{ target }}"
+    </script>
+    <title>Page Redirection</title>
+</head>
+<body>
+  <!-- Note: don't tell people to `click` the link, just tell them that it is a link. -->
+  If you are not redirected automatically, follow the <a href="{{ target }}">link to {{ name }}</a>
+</body>
+</html>
\ No newline at end of file

Code/Mantid/docs/source/conf.py

+# -*- coding: utf-8 -*-
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+import sphinx_bootstrap_theme
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../sphinxext'))
+
+# -- General configuration ------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.pngmath',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.doctest',
+    'mantiddoc.directives'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'MantidProject'
+copyright = u'2014, Mantid'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.01'
+# The full version, including alpha/beta/rc tags.
+release = '0.01'
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'bootstrap'
+
+# Theme-specific options to customize the look and feel of a theme.
+# We config the bootstrap settings here, and apply CSS changes in
+# custom.css rather than here.
+html_theme_options = {
+    # Navigation bar title.
+    'navbar_title': " ", # deliberate single space so it's not visible
+    # Tab name for entire site.
+    'navbar_site_name': "Mantid",
+    # Add links to the nav bar. Second param of tuple is true to create absolute url.
+    'navbar_links': [
+        ("Home", "/"),
+        ("Download", "http://download.mantidproject.org", True),
+        ("Documentation", "/documentation"),
+        ("Contact Us", "/contact-us"),
+    ],
+    # Do not show the "Show source" button.
+    'source_link_position': "no",
+    # Remove the local TOC from the nav bar
+    'navbar_pagenav': False,
+    # Hide the next/previous in the nav bar.
+    'navbar_sidebarrel': False,
+    # Use the latest version.
+    'bootstrap_version': "3",
+    # Ensure the nav bar always stays on top of page.
+    'navbar_fixed_top': "true",
+}
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = os.path.relpath('../../Images/Mantid_Logo_Transparent_Cropped.png')
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+html_use_smartypants = True
+
+# Hide the Sphinx usage as we reference it on github instead.
+html_show_sphinx = False
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+html_show_copyright = True

Code/Mantid/docs/source/images/.gitignore

+screenshots/*

Code/Mantid/docs/source/images/README.md

+Contains images for the documentation
+
+The algorithm screenshots are automatically generated into a `screenshots` subdirectory and this subdirectory has been added to the `.gitignore` in this directory