Sphinx 9 deprecations

docs/source/conf.py

@@ -206,7 +206,7 @@ def setup(app):
 
 # -- Options for selected builder output ---------------------------------------
 # Default is to use standard HTML theme unless the qthelp tag is specified
-html_theme_cfg = "conf-qthelp.py" if "qthelp" in [k.strip() for k in tags.tags] else "conf-html.py"
+html_theme_cfg = "conf-qthelp.py" if "qthelp" in [k.strip() for k in tags] else "conf-html.py"
 # Python 3 removed execfile...
 exec(compile(open(html_theme_cfg).read(), html_theme_cfg, "exec"))
 

docs/sphinxext/mantiddoc/directives/amalgamate.py

@@ -5,7 +5,7 @@
 #   Institut Laue - Langevin & CSNS, Institute of High Energy Physics, CAS
 # SPDX - License - Identifier: GPL - 3.0 +
 from mantiddoc.directives.base import BaseDirective
-
+from pathlib import PurePosixPath
 import os
 
 
@@ -36,23 +36,23 @@ def execute(self):
         if os.path.exists(script_dir):
             for file in os.listdir(script_dir):
                 if file.endswith(".rst"):
-                    with open(script_dir + "/" + file) as f:
+                    with open(script_dir.joinpath(file)) as f:
                         contents = f.read()
                         self.add_rst(contents)
 
         return []
 
     def getPath(self):
         # the location of documentation
-        source_dir = self.state.document.settings.env.srcdir
+        source_dir = PurePosixPath(self.state.document.settings.env.srcdir)
         # the location of the release notes for this version
         release_dir = self.source().rsplit("/", 1)[0]
         # argument provided to amalgamate directive
         args = self.arguments[0]
         if args[0] != "/":
             args = "/" + args
         path_to_notes = release_dir + args
-        return os.path.abspath(os.path.join(source_dir, path_to_notes))
+        return source_dir.joinpath(path_to_notes)
 
 
 def setup(app):

docs/sphinxext/mantiddoc/directives/base.py

@@ -11,6 +11,7 @@
 from mantid.api import AlgorithmFactory, AlgorithmManager, FunctionFactory
 from mantiddoc import get_logger
 from typing import List
+from pathlib import PurePosixPath
 
 ALG_DOCNAME_RE = re.compile(r"^([A-Z][a-zA-Z0-9]+)-v([0-9][0-9]*)$")
 FIT_DOCNAME_RE = re.compile(r"^([A-Z][a-zA-Z0-9]+)$")
@@ -77,7 +78,7 @@ def screenshots_dir(self):
         if screenshots_dir is None or screenshots_dir == "":
             return None
         else:
-            return screenshots_dir
+            return PurePosixPath(screenshots_dir)
 
     def add_rst(self, text):
         """

docs/sphinxext/mantiddoc/directives/categories.py

@@ -16,7 +16,7 @@
 from mantiddoc.directives.base import AlgorithmBaseDirective, algorithm_name_and_version  # pylint: disable=unused-import
 from sphinx.util.osutil import relative_uri
 import os
-import posixpath
+from pathlib import PurePosixPath
 
 CATEGORY_PAGE_TEMPLATE = "category.html"
 ALG_CATEGORY_PAGE_TEMPLATE = "algorithmcategories.html"
@@ -77,7 +77,7 @@ def link(self, base, ext=".html"):
         Returns:
           str: A string containing the link to reach this item
         """
-        link = relative_uri(base=to_unix_style_path(base), to=self.location)
+        link = relative_uri(str(base), to=str(self.location))
         if not link.endswith(ext):
             link += ext
         return link
@@ -124,12 +124,15 @@ def __init__(self, name, docname, src_path):
           name (str): The name of the category
           docname (str): Relative path to document from root directory
         """
-        self.src_path = to_unix_style_path(src_path)
-        docname = to_unix_style_path(docname)
-        self.section = docname.lower().split("/")[0]
-        dirpath, filename = posixpath.split(docname)
-        html_dir = dirpath + "/" + CATEGORIES_DIR
-        self.html_path = html_dir + "/" + to_unix_style_path(name) + ".html"
+        self.src_path = PurePosixPath(src_path)
+        docname = PurePosixPath(docname)
+        self.section = docname.parts[0]
+        dirpath = docname.parent
+        html_dir = dirpath.joinpath(CATEGORIES_DIR)
+        # name can arrive with a format like "MyAlgorithmCategory\\NameOfAlgorithm", so we
+        # have to sort those slashes out
+        name_with_slashes_fixed = name.replace("\\", "/").replace("//", "/")
+        self.html_path = html_dir.joinpath(name_with_slashes_fixed + ".html")
         super(Category, self).__init__(name, self.html_path)
         self.pages = set([])
         self.subcategories = set([])
@@ -312,20 +315,6 @@ def register_category(self, categ_name, env):
 # ---------------------------------------------------------------------------------
 
 
-def to_unix_style_path(path):
-    """
-    Replaces any backslashes in the given string with forward slashes
-    and replace consecutive forward slashes with a single forward slash.
-
-    Arguments:
-      path: A string possibly containing backslashes
-    """
-    return path.replace("\\", "/").replace("//", "/")
-
-
-# ---------------------------------------------------------------------------------
-
-
 def html_collect_pages(app):
     """
     Callback for the 'html-collect-pages' Sphinx event. Adds category
@@ -384,21 +373,21 @@ def create_category_pages(app):
         context["outpath"] = category.html_path
 
         # jinja appends .html to output name
-        category_html_path_noext = posixpath.splitext(category.html_path)[0]
-        yield (category_html_path_noext, context, template)
+        category_html_path_noext = category.html_path.with_suffix("")
+        yield (str(category_html_path_noext), context, template)
 
         # Now any additional index pages if required
         if category.name in INDEX_CATEGORIES:
             # index in categories directory
-            category_html_dir = posixpath.join(category.name.lower(), "categories")
-            category_html_path_noext = posixpath.join(category_html_dir, "index")
-            yield (category_html_path_noext, context, template)
+            category_html_dir = PurePosixPath(category.name.lower(), "categories")
+            category_html_path_noext = category_html_dir.joinpath("index")
+            yield (str(category_html_path_noext), context, template)
 
             # index in document directory
-            document_dir = posixpath.dirname(category_html_dir)
-            category_html_path_noext = posixpath.join(document_dir, "index")
-            context["outpath"] = category_html_path_noext + ".html"
-            yield (category_html_path_noext, context, template)
+            document_dir = category_html_dir.parent
+            category_html_path_noext = document_dir.joinpath("index")
+            context["outpath"] = str(category_html_path_noext.with_suffix(".html"))
+            yield (str(category_html_path_noext), context, template)
 
     # create the top level algorithm category
     yield create_top_algorithm_category(categories)
@@ -423,16 +412,16 @@ def create_top_algorithm_category(categories):
     # create a Top level algorithms category page
     # Initialise the lists
     all_top_categories = []
-    category_src_dir = ""
+    category_src_dir = PurePosixPath("")
     # If the category is a top category it will not contain "\\"
     for top_name, top_category in categories.items():
         # Add all the top level categories
         if "\\" not in top_name and top_category.section == "algorithms":
             # get additional text for each category
             # if is exists it is in src_path/caterories/name.txt
-            alg_src_dir = posixpath.dirname(top_category.src_path)
-            category_src_dir = posixpath.join(alg_src_dir, "categories")
-            category_text_path = posixpath.join(category_src_dir, top_name) + ".txt"
+            alg_src_dir = top_category.src_path.parent
+            category_src_dir = alg_src_dir.joinpath("categories")
+            category_text_path = category_src_dir.joinpath(top_name).with_suffix(".txt")
             if os.path.isfile(category_text_path):
                 with open(category_text_path) as f:
                     top_category.additional_text = f.read()
@@ -442,20 +431,24 @@ def create_top_algorithm_category(categories):
 
     # split the full list into subsections
     general_categories = all_top_categories
-    technique_categories = extract_matching_categories(general_categories, posixpath.join(category_src_dir, "techniquecategories") + ".txt")
-    facility_categories = extract_matching_categories(general_categories, posixpath.join(category_src_dir, "facilitycategories") + ".txt")
+    technique_categories = extract_matching_categories(
+        general_categories, category_src_dir.joinpath("techniquecategories").with_suffix(".txt")
+    )
+    facility_categories = extract_matching_categories(
+        general_categories, category_src_dir.joinpath("facilitycategories").with_suffix(".txt")
+    )
 
     # create the page
     top_context = {}
-    top_category_html_path_noext = posixpath.join("algorithms", "index")
-    top_context["outpath"] = top_category_html_path_noext + ".html"
+    top_category_html_path_noext = PurePosixPath("algorithms", "index")
+    top_context["outpath"] = str(top_category_html_path_noext.with_suffix(".html"))
     # set the content
     top_context["pages"] = []
     top_context["generalcategories"] = sorted(general_categories, key=lambda x: x.name)
     top_context["techniquecategories"] = sorted(technique_categories, key=lambda x: x.name)
     top_context["facilitycategories"] = sorted(facility_categories, key=lambda x: x.name)
     top_context["title"] = "Algorithm Contents"
-    top_html_path_noext = posixpath.join("algorithms", "index")
+    top_html_path_noext = str(PurePosixPath("algorithms", "index"))
     return (top_html_path_noext, top_context, template)
 
 

docs/sphinxext/mantiddoc/directives/diagram.py

@@ -9,6 +9,7 @@
 import os
 from string import Template
 import subprocess
+from pathlib import PurePosixPath
 
 STYLE = dict()
 
@@ -47,7 +48,7 @@ def diagrams_dir(self):
         if diagrams_dir is None or diagrams_dir == "":
             return None
         else:
-            return diagrams_dir
+            return PurePosixPath(diagrams_dir)
 
     def run(self):
         """
@@ -81,14 +82,14 @@ def execute(self):
         if diagram_name[-4:] != ".dot":
             raise RuntimeError("Diagrams need to be referred to by their filename, including '.dot' extension.")
 
-        in_path = os.path.join(env.srcdir, "diagrams", diagram_name)
-        out_path = os.path.join(diagrams_dir, diagram_name[:-4] + ".svg")
+        in_path = PurePosixPath(env.srcdir, "diagrams", diagram_name)
+        out_path = PurePosixPath(diagrams_dir, diagram_name[:-4] + ".svg")
 
         # Generate the diagram
         try:
             in_src = open(in_path, "r").read()
         except Exception:
-            raise RuntimeError("Cannot find dot-file: '" + diagram_name + "' in '" + os.path.join(env.srcdir, "diagrams"))
+            raise RuntimeError("Cannot find dot-file: '" + diagram_name + "' in '" + PurePosixPath(env.srcdir, "diagrams"))
 
         out_src = Template(in_src).substitute(STYLE)
         out_src = out_src.encode()
@@ -97,6 +98,7 @@ def execute(self):
         gviz.wait()
 
         # relative path to image, in unix style
+        # pathlib.Path.relative_to() will not work here, the method won't traverse up then down again
         rel_path = os.path.relpath(out_path, env.srcdir).replace("\\", "/")
 
         self.add_rst(".. image:: /" + rel_path + "\n\n")

docs/sphinxext/mantiddoc/directives/interface.py

@@ -6,6 +6,7 @@
 # SPDX - License - Identifier: GPL - 3.0 +
 from mantiddoc.directives.base import BaseDirective  # pylint: disable=unused-import
 import os
+from pathlib import Path, PurePosixPath
 
 
 class InterfaceDirective(BaseDirective):
@@ -83,22 +84,23 @@ def _insert_screenshot_link(self, picture, align=None, width=None):
         # conf.py file and a relative path is relative to the directory where the current rst file
         # is located.
         if picture:
-            screenshots_dir, filename = os.path.split(picture.imgpath)
+            picture_imgpath = Path(picture.imgpath)
+            screenshots_dir = picture_imgpath.parent
+            filename = picture_imgpath.name
 
             if width is None:
                 # No width provided, use screenshot width
                 width = picture.width
 
             # relative path to image
-            rel_path = os.path.relpath(screenshots_dir, env.srcdir)
-            # This is a href link so is expected to be in unix style
-            rel_path = rel_path.replace("\\", "/")
+            # pathlib.Path.relative_to() will not work here, the method won't traverse up then down again
+            rel_path = os.path.relpath(screenshots_dir, env.srcdir).replace("\\", "/")
             # stick a "/" as the first character so Sphinx computes relative location from source directory
-            path = "/" + rel_path + "/" + filename
+            path = PurePosixPath("/").joinpath(rel_path).joinpath(filename)
             caption = ""
         else:
             # use stock not found image
-            path = "/images/ImageNotFound.png"
+            path = PurePosixPath("/images/ImageNotFound.png")
             width = 200
             caption = "Enable screenshots using DOCS_SCREENSHOTS in CMake"
 

docs/sphinxext/mantiddoc/directives/sourcelink.py

@@ -7,6 +7,7 @@
 import os
 import mantid
 from .base import AlgorithmBaseDirective
+from pathlib import Path, PurePosixPath
 
 
 class SourceLinkError(Exception):
@@ -89,7 +90,7 @@ def execute(self):
                 file_paths[extension] = None
             else:
                 # prepend the base framework directory
-                fname = os.path.join(self.source_root, file_paths[extension])
+                fname = self.source_root.joinpath(file_paths[extension])
                 file_paths[extension] = fname
                 if not os.path.exists(file_paths[extension]):
                     error_string += "Cannot find {} file at {}\n".format(extension, file_paths[extension])
@@ -150,10 +151,9 @@ def source_root(self):
         """
         if self.__source_root is None:
             env = self.state.document.settings.env
-            direc = env.srcdir  # = C:\Mantid\Code\Mantid\docs\source
-            direc = os.path.join(direc, "..", "..")  # assume root is two levels up
-            direc = os.path.abspath(direc)
-            self.__source_root = direc  # pylint: disable=protected-access
+            # assume root is two levels up
+            direc = Path(env.srcdir, "..", "..").resolve()  # = C:\Mantid\Code\Mantid\docs\source
+            self.__source_root = PurePosixPath(direc)  # pylint: disable=protected-access
 
         return self.__source_root
 
@@ -162,12 +162,11 @@ def parse_source_tree(self):
         Fills the file_lookup dictionary after parsing the source code
         """
         env = self.state.document.settings.env
-        builddir = env.doctreedir  # there should be a better setting option
-        builddir = os.path.join(builddir, "..", "..")
-        builddir = os.path.abspath(builddir)
+        builddir = Path(env.doctreedir, "..", "..")  # there should be a better setting option
+        builddir = builddir.resolve()
 
         for dir_name, _, file_list in os.walk(self.source_root):
-            if dir_name.startswith(builddir):
+            if builddir in Path(dir_name).resolve().parents:
                 continue  # don't check or add to the cache
             for fname in file_list:
                 (base_name, file_extensions) = os.path.splitext(fname)
@@ -180,7 +179,7 @@ def parse_source_tree(self):
                         self.file_lookup[base_name] = {}
                     if file_extensions not in self.file_lookup[base_name].keys():
                         self.file_lookup[base_name][file_extensions] = []
-                    self.file_lookup[base_name][file_extensions].append(os.path.join(dir_name, fname))
+                    self.file_lookup[base_name][file_extensions].append(PurePosixPath(dir_name, fname))
 
     def output_to_page(self, file_paths, file_name, sanity_checks):
         """
@@ -243,9 +242,7 @@ def output_path_to_page(self, filepath, extension):
         """
         Outputs the source link for a file to the rst page
         """
-        _, f_name = os.path.split(filepath)
-
-        self.add_rst("{}: `{} <{}>`_\n\n".format(self.file_types[extension], f_name, self.convert_path_to_github_url(filepath)))
+        self.add_rst("{}: `{} <{}>`_\n\n".format(self.file_types[extension], str(filepath.name), self.convert_path_to_github_url(filepath)))
 
     def convert_path_to_github_url(self, file_path):
         """
@@ -254,9 +251,9 @@ def convert_path_to_github_url(self, file_path):
         example path Framework/Algorithms/inc/MantidAlgorithms/MergeRuns.h
         example url  https://github.com/mantidproject/mantid/blob/master/Framework/Algorithms/inc/MantidAlgorithms/MergeRuns.h
         """
-        url = file_path
+        url = str(file_path)
         # remove the directory path
-        url = url.replace(self.source_root, "")
+        url = url.replace(str(self.source_root), "")
         # harmonize slashes
         url = url.replace("\\", "/")
         # prepend the github part