Require versioned algorithm files

Implements a test for a simple redirect system to the highest version
Refs #9521

Code/Mantid/docs/sphinxext/mantiddoc/directives/algorithm.py

@@ -1,26 +1,28 @@
 from base import BaseDirective
 import os
 
+REDIRECT_TEMPLATE = "redirect.html"
+
 class AlgorithmDirective(BaseDirective):
 
     """
     Adds a referenceable link for a given algorithm, a title,
     and a screenshot of the algorithm to an rst file.
     """
 
-    required_arguments, optional_arguments = 1, 0
+    required_arguments, optional_arguments = 0, 0
 
     def run(self):
         """
         Called by Sphinx when the ..algorithm:: directive is encountered
         """
-        algorithm_name = str(self.arguments[0])
+        algorithm_name, version = self._algorithm_name_and_version()
 
         # Seperate methods for each unique piece of functionality.
         reference = self._make_reference_link(algorithm_name)
         title = self._make_header(algorithm_name, True)
         toc = self._make_local_toc()
-        imgpath = self._create_screenshot(algorithm_name)
+        imgpath = self._create_screenshot(algorithm_name, version)
         screenshot = self._make_screenshot_link(algorithm_name, imgpath)
 
         return self._insert_rest(reference + title + screenshot + toc)
@@ -36,20 +38,21 @@ def _make_reference_link(self, algorithm_name):
         Returns:
           str: A ReST formatted reference.
         """
-        return ".. _%s:\n" % algorithm_name
+        return ".. _algorithm|%s:\n" % algorithm_name
 
     def _make_local_toc(self):
         return ".. contents:: Table of Contents\n    :local:\n"
 
-    def _create_screenshot(self, algorithm_name):
+    def _create_screenshot(self, algorithm_name, version):
         """
         Creates a screenshot for the named algorithm in an "images/screenshots"
         subdirectory of the currently processed document
 
-        The file will be named "algorithmname_dlg.png", e.g. Rebin_dlg.png
+        The file will be named "algorithmname-vX_dlg.png", e.g. Rebin-v1_dlg.png
 
         Args:
           algorithm_name (str): The name of the algorithm.
+          version (int): The version of the algorithm
 
         Returns:
           str: The full path to the created image
@@ -62,7 +65,7 @@ def _create_screenshot(self, algorithm_name):
             os.makedirs(screenshots_dir)
 
         try:
-            imgpath = algorithm_screenshot(algorithm_name, screenshots_dir)
+            imgpath = algorithm_screenshot(algorithm_name, screenshots_dir, version=version)
         except Exception, exc:
             env.warn(env.docname, "Unable to generate screenshot for '%s' - %s" % (algorithm_name, str(exc)))
             imgpath = os.path.join(screenshots_dir, "failed_dialog.png")
@@ -85,7 +88,7 @@ def _make_screenshot_link(self, algorithm_name, img_path):
         """
         format_str = ".. figure:: %s\n"\
                      "    :class: screenshot\n\n"\
-                     "    %s\n"
+                     "    %s\n\n"
 
         filename = os.path.split(img_path)[1]
         path = "/images/screenshots/" + filename
@@ -111,6 +114,18 @@ def _screenshot_directory(self, env):
 
 ############################################################################################################
 
+def html_collect_pages(app):
+    """
+    Write out unversioned algorithm pages that redirect to the highest version of the algorithm
+    """
+    name = "algorithms/Rebin"
+    context = {"name" : "Rebin", "target" : "Rebin-v1.html"}
+    template = REDIRECT_TEMPLATE
+
+    return [(name, context, template)]
+
+############################################################################################################
+
 def setup(app):
     """
     Setup the directives when the extension is activated
@@ -119,3 +134,7 @@ def setup(app):
       app: The main Sphinx application object
     """
     app.add_directive('algorithm', AlgorithmDirective)
+
+    # connect event html collection to handler
+    app.connect("html-collect-pages", html_collect_pages)
+

Code/Mantid/docs/sphinxext/mantiddoc/directives/aliases.py

@@ -7,24 +7,25 @@ class AliasesDirective(BaseDirective):
     Obtains the aliases for a given algorithm based on it's name.
     """
 
-    required_arguments, optional_arguments = 1, 0
+    required_arguments, optional_arguments = 0, 0
 
     def run(self):
         """
         Called by Sphinx when the ..aliases:: directive is encountered.
         """
         title = self._make_header("Aliases")
-        alias = self._get_alias(str(self.arguments[0]))
+        alias = self._get_alias()
         return self._insert_rest(title + alias)
 
-    def _get_alias(self, algorithm_name):
+    def _get_alias(self):
         """
         Return the alias for the named algorithm.
 
         Args:
           algorithm_name (str): The name of the algorithm to get the alias for.
         """
-        alg = self._create_mantid_algorithm(algorithm_name)
+        name, version = self._algorithm_name_and_version()
+        alg = self._create_mantid_algorithm(name, version)
         return "This algorithm is also known as: " + "**" + alg.alias() + "**"
 
 

Code/Mantid/docs/sphinxext/mantiddoc/directives/base.py

@@ -1,6 +1,6 @@
 from docutils import statemachine
 from docutils.parsers.rst import Directive
-
+import re
 
 class BaseDirective(Directive):
 
@@ -11,21 +11,40 @@ class BaseDirective(Directive):
     has_content = True
     final_argument_whitespace = True
 
-    def _make_header(self, name, title=False):
+    alg_docname_re = re.compile(r'^([A-Z][a-zA-Z0-9]+)-v([0-9][0-9]*)$')
+
+    def _algorithm_name_and_version(self):
+        """
+        Returns the name and version of an algorithm based on the name of the
+        document. The expected name of the document is "AlgorithmName-v?", which
+        is the name of the file with the extension removed
+        """
+        env = self.state.document.settings.env
+        # env.docname includes path, using forward slashes, from root of documentation directory
+        docname = env.docname.split("/")[-1]
+        match = self.alg_docname_re.match(docname)
+        if not match or len(match.groups()) != 2:
+            raise RuntimeError("Document filename '%s.rst' does not match the expected format: AlgorithmName-vX.rst" % docname)
+
+        grps = match.groups()
+        return (str(grps[0]), int(grps[1]))
+
+    def _make_header(self, name, pagetitle=False):
         """
         Makes a ReStructuredText title from the algorithm's name.
 
         Args:
           algorithm_name (str): The name of the algorithm to use for the title.
-          title (bool): If True, line is inserted above & below algorithm name.
+          pagetitle (bool): If True, line is inserted above & below algorithm name.
 
         Returns:
           str: ReST formatted header with algorithm_name as content.
         """
-        line = "\n" + "-" * len(name) + "\n"
-        if title:
+        if pagetitle:
+            line = "\n" + "=" * len(name) + "\n"
             return line + name + line
         else:
+            line = "\n" + "-" * len(name) + "\n"
             return name + line
 
     def _insert_rest(self, text):
@@ -41,17 +60,18 @@ def _insert_rest(self, text):
         self.state_machine.insert_input(statemachine.string2lines(text), "")
         return []
 
-    def _create_mantid_algorithm(self, algorithm_name):
+    def _create_mantid_algorithm(self, algorithm_name, version):
         """
         Create and initializes a Mantid algorithm.
 
         Args:
           algorithm_name (str): The name of the algorithm to use for the title.
+          version (int): Version of the algorithm to create
 
         Returns:
           algorithm: An instance of a Mantid algorithm.
         """
         from mantid.api import AlgorithmManager
-        alg = AlgorithmManager.createUnmanaged(algorithm_name)
+        alg = AlgorithmManager.createUnmanaged(algorithm_name, version)
         alg.initialize()
         return alg