diff --git a/Code/Mantid/docs/sphinxext/mantiddoc/directives/algorithm.py b/Code/Mantid/docs/sphinxext/mantiddoc/directives/algorithm.py
index c29a49b32775a7299ff710096c01d37515406147..ac80154a4f7207761d24bff92cd9d6df6ba47630 100644
--- a/Code/Mantid/docs/sphinxext/mantiddoc/directives/algorithm.py
+++ b/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 @@ class AlgorithmDirective(BaseDirective):
"""
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 @@ class AlgorithmDirective(BaseDirective):
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,14 +100,14 @@ class AlgorithmDirective(BaseDirective):
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
@@ -101,11 +115,7 @@ class AlgorithmDirective(BaseDirective):
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"\
@@ -113,9 +123,9 @@ class AlgorithmDirective(BaseDirective):
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 @@ class AlgorithmDirective(BaseDirective):
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):
diff --git a/Code/Mantid/docs/sphinxext/mantiddoc/directives/aliases.py b/Code/Mantid/docs/sphinxext/mantiddoc/directives/aliases.py
index b44255753ae205c75fc62e98de96a75cf48b460c..9ee58c7fe8074605b34f618eb1a60ce203848878 100644
--- a/Code/Mantid/docs/sphinxext/mantiddoc/directives/aliases.py
+++ b/Code/Mantid/docs/sphinxext/mantiddoc/directives/aliases.py
@@ -27,8 +27,7 @@ class AliasesDirective(BaseDirective):
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 ""
diff --git a/Code/Mantid/docs/sphinxext/mantiddoc/directives/base.py b/Code/Mantid/docs/sphinxext/mantiddoc/directives/base.py
index c080f4aeb4faa5433e4deeb0ceb7dc8d6001cd32..b6980693d7be1899317820781e5b1f737c62a9df 100644
--- a/Code/Mantid/docs/sphinxext/mantiddoc/directives/base.py
+++ b/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):
"""
diff --git a/Code/Mantid/docs/sphinxext/mantiddoc/directives/categories.py b/Code/Mantid/docs/sphinxext/mantiddoc/directives/categories.py
index ec76149057cb3d4d530a0a4b1320088dc3faf2a3..4c829f8680cbae366329f9652b0d3631e765a7e3 100644
--- a/Code/Mantid/docs/sphinxext/mantiddoc/directives/categories.py
+++ b/Code/Mantid/docs/sphinxext/mantiddoc/directives/categories.py
@@ -214,8 +214,7 @@ class AlgorithmCategoryDirective(CategoriesDirective):
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 @@ class AlgorithmCategoryDirective(CategoriesDirective):
"""
Returns the name of the item as it should appear in the category
"""
- return self._algorithm_name_and_version()[0]
+ return self.algorithm_name()
#---------------------------------------------------------------------------------
diff --git a/Code/Mantid/docs/sphinxext/mantiddoc/directives/properties.py b/Code/Mantid/docs/sphinxext/mantiddoc/directives/properties.py
index 440e11d4bd7ad943980f35c0004b02a10476e89c..35455462ed9d78587f6aeed1e40e7c161029bdf2 100644
--- a/Code/Mantid/docs/sphinxext/mantiddoc/directives/properties.py
+++ b/Code/Mantid/docs/sphinxext/mantiddoc/directives/properties.py
@@ -21,9 +21,7 @@ class PropertiesDirective(BaseDirective):
"""
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.
diff --git a/Code/Mantid/docs/sphinxext/mantiddoc/directives/summary.py b/Code/Mantid/docs/sphinxext/mantiddoc/directives/summary.py
index 2432a2fc407608c8039f33cb3794ced32578d83b..6b3bdb4ec9bafcc1fa5fefe6bd3bba0582764084 100644
--- a/Code/Mantid/docs/sphinxext/mantiddoc/directives/summary.py
+++ b/Code/Mantid/docs/sphinxext/mantiddoc/directives/summary.py
@@ -24,8 +24,7 @@ class SummaryDirective(BaseDirective):
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()