Add deprecation message if neccesary

Also regorganised to base to give easier access to algorithm name/version.
Refs #9521

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

@@ -1,13 +1,28 @@
 from base import BaseDirective
+from docutils import nodes
+from sphinx.locale import _
+from sphinx.util.compat import make_admonition
 import os
+import re
 
 REDIRECT_TEMPLATE = "redirect.html"
 
+DEPRECATE_USE_ALG_RE = re.compile(r'Use\s([A-Z][a-zA-Z0-9]+)\sinstead')
+
+#--------------------------------------------------------------------------
 class AlgorithmDirective(BaseDirective):
 
     """
-    Adds a referenceable link for a given algorithm, a title,
-    and a screenshot of the algorithm to an rst file.
+    Inserts details of an algorithm by querying Mantid
+
+    Adds:
+     - A referenceable link for use with Sphinx ":ref:`` tags", if this is
+       the highest version of the algorithm being processed
+     - A title
+     - A screenshot of the algorithm
+     - Table of contents
+
+    If the algorithms is deprecated then a warning is inserted.
     """
 
     required_arguments, optional_arguments = 0, 0
@@ -16,30 +31,30 @@ def run(self):
         """
         Called by Sphinx when the ..algorithm:: directive is encountered
         """
-        algorithm_name, version = self._algorithm_name_and_version()
-        self._track_algorithm(algorithm_name, version)
+        self._track_algorithm()
 
-        # 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, version)
-        screenshot = self._make_screenshot_link(algorithm_name, imgpath)
+        self._insert_reference_link()
+        self._insert_pagetitle()
+        imgpath = self._create_screenshot()
+        self._insert_screenshot_link(imgpath)
+        self._insert_toc()
+        self._insert_deprecation_warning()
 
-        return self._insert_rest(reference + title + screenshot + toc)
+        self.commit_rst()
+        return []
 
-    def _track_algorithm(self, name, version):
+    def _track_algorithm(self):
         """
-        Keep a track of the highest versions of algorithms encountered
-        
-        Arguments:
-          name (str): Name of the algorithm
-          version (int): Integer version number
+        Keep a track of the highest versions of algorithms encountered.
+        The algorithm name and version are retrieved from the document name.
+        See BaseDirective::set_algorithm_and_version()
         """
         env = self.state.document.settings.env
         if not hasattr(env, "algorithm"):
             env.algorithms = {}
         #endif
+
+        name, version = self.algorithm_name(), self.algorithm_version()
         algorithms = env.algorithms
         if name in algorithms:
             prev_version = algorithms[name][1]
@@ -48,33 +63,32 @@ def _track_algorithm(self, name, version):
         else:
             algorithms[name] = (name, version)
 
-    def _make_reference_link(self, algorithm_name):
+    def _insert_reference_link(self):
         """
         Outputs a reference to the top of the algorithm's rst
         of the form .. _AlgorithmName:
+        """
+        self.add_rst(".. _algorithm|%s:\n" % self.algorithm_name())
 
-        Args:
-          algorithm_name (str): The name of the algorithm to reference.
-
-        Returns:
-          str: A ReST formatted reference.
+    def _insert_pagetitle(self):
         """
-        return ".. _algorithm|%s:\n" % algorithm_name
+        Outputs a title for the page
+        """
+        self.add_rst(self._make_header(self.algorithm_name(), True))
 
-    def _make_local_toc(self):
-        return ".. contents:: Table of Contents\n    :local:\n"
+    def _insert_toc(self):
+        """
+        Outputs a title for the page
+        """
+        self.add_rst(".. contents:: Table of Contents\n    :local:\n")
 
-    def _create_screenshot(self, algorithm_name, version):
+    def _create_screenshot(self):
         """
         Creates a screenshot for the named algorithm in an "images/screenshots"
         subdirectory of the currently processed document
 
         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
         """
@@ -86,36 +100,32 @@ def _create_screenshot(self, algorithm_name, version):
             os.makedirs(screenshots_dir)
 
         try:
-            imgpath = algorithm_screenshot(algorithm_name, screenshots_dir, version=version)
+            imgpath = algorithm_screenshot(self.algorithm_name(), screenshots_dir, version=self.algorithm_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")
 
         return imgpath
 
-    def _make_screenshot_link(self, algorithm_name, img_path):
+    def _insert_screenshot_link(self, img_path):
         """
         Outputs an image link with a custom :class: style. The filename is
         extracted from the path given and then a link to /images/screenshots/filename.png
         is created. Sphinx handles copying the files over to the build directory
         and reformatting the links
 
         Args:
-          algorithm_name (str): The name of the algorithm that the screenshot represents
           img_path (str): The full path as on the filesystem to the image
-
-        Returns:
-          str: A ReST formatted reference.
         """
         format_str = ".. figure:: %s\n"\
                      "    :class: screenshot\n\n"\
                      "    %s\n\n"
 
         filename = os.path.split(img_path)[1]
         path = "/images/screenshots/" + filename
-        caption = "A screenshot of the **" + algorithm_name + "** dialog."
+        caption = "A screenshot of the **" + self.algorithm_name() + "** dialog."
 
-        return format_str % (path, caption)
+        self.add_rst(format_str % (path, caption))
 
     def _screenshot_directory(self, env):
         """
@@ -133,6 +143,27 @@ def _screenshot_directory(self, env):
         cfg_dir = env.app.srcdir
         return os.path.join(cfg_dir, "images", "screenshots")
 
+    def _insert_deprecation_warning(self):
+        """
+        If the algorithm version is deprecated then construct a warning message
+        """
+        from mantid.api import DeprecatedAlgorithmChecker
+
+        checker = DeprecatedAlgorithmChecker(self.algorithm_name(), self.algorithm_version())
+        msg = checker.isDeprecated()
+        if len(msg) == 0:
+            return
+
+        # Check for message to use another algorithm an insert a link
+        match = DEPRECATE_USE_ALG_RE.search(msg)
+        print "TESTING",msg
+        print "TESTING",match,match.groups()
+        if match is not None and len(match.groups()) == 1:
+            name = match.group(0)
+            msg = DEPRECATE_USE_ALG_RE.sub(r"Use :ref:`algorithm|\1` instead.", msg)
+            print "TESTING",msg
+        self.add_rst(".. warning:: %s" % msg)
+
 ############################################################################################################
 
 def html_collect_pages(app):

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

@@ -27,8 +27,7 @@ def _get_alias(self):
         Args:
           algorithm_name (str): The name of the algorithm to get the alias for.
         """
-        name, version = self._algorithm_name_and_version()
-        alg = self._create_mantid_algorithm(name, version)
+        alg = self._create_mantid_algorithm(self.algorithm_name(), self.algorithm_version())
         alias_name = alg.alias()
         if len(alias_name) == 0:
             return ""

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

@@ -32,18 +32,57 @@ class BaseDirective(Directive):
     """
     Contains shared functionality for Mantid custom directives.
     """
-
-    has_content = True
+    has_content = False
     final_argument_whitespace = True
 
-    def _algorithm_name_and_version(self):
+    algm_name = None
+    algm_version = None
+    rst_lines = None
+
+    def algorithm_name(self):
+        """
+        Returns the algorithm name as parsed from the document name
+        """
+        if self.algm_name is None:
+            self._set_algorithm_name_and_version()
+        return self.algm_name
+
+    def algorithm_version(self):
+        """
+        Returns the algorithm version as parsed from the document name
+        """
+        if self.algm_version is None:
+            self._set_algorithm_name_and_version()
+        return self.algm_version
+
+    def _set_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
-        return algorithm_name_and_version(env.docname)
+        self.algm_name, self.algm_version = algorithm_name_and_version(env.docname)
+
+    def add_rst(self, text):
+        """
+        Appends given reST into a managed list. It is NOT inserted into the
+        document until commit_rst() is called
+
+        Args:
+          text (str): reST to track
+        """
+        if self.rst_lines is None:
+            self.rst_lines = []
+
+        self.rst_lines.extend(statemachine.string2lines(text))
+
+    def commit_rst(self):
+        """
+        Inserts the currently tracked rst lines into the state_machine
+        """
+        self.state_machine.insert_input(self.rst_lines, "")
+        self.rst_lines = []
 
     def _make_header(self, name, pagetitle=False):
         """

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

@@ -214,8 +214,7 @@ def _get_categories_list(self):
           list: A list of strings containing the required categories
         """
         category_list = ["Algorithms"]
-        algname, version = self._algorithm_name_and_version()
-        alg_cats = self._create_mantid_algorithm(algname, version).categories()
+        alg_cats = self._create_mantid_algorithm(self.algorithm_name(), self.algorithm_version()).categories()
         for cat in alg_cats:
             # double up the category separators so they are not treated as escape characters
             category_list.append(cat.replace("\\", "\\\\"))
@@ -226,7 +225,7 @@ def _get_display_name(self):
         """
         Returns the name of the item as it should appear in the category
         """
-        return self._algorithm_name_and_version()[0]
+        return self.algorithm_name()
 
 #---------------------------------------------------------------------------------
 

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

@@ -21,9 +21,7 @@ def _populate_properties_table(self):
         """
         Populates the ReST table with algorithm properties.
         """
-        name, version = self._algorithm_name_and_version()
-
-        alg = self._create_mantid_algorithm(name, version)
+        alg = self._create_mantid_algorithm(self.algorithm_name(), self.algorithm_version())
         alg_properties = alg.getProperties()
 
         # Stores each property of the algorithm in a tuple.

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

@@ -24,8 +24,7 @@ def _get_summary(self):
         Args:
           algorithm_name (str): The name of the algorithm.
         """
-        name, version = self._algorithm_name_and_version()
-        alg = self._create_mantid_algorithm(name, version)
+        alg = self._create_mantid_algorithm(self.algorithm_name(), self.algorithm_version())
         return alg.getWikiSummary()