Fixes formatting issue for "sub" tag conversion in Python API documentation (#4375)

* Replaces sub tags for python API docs

* Changes string to pathlib

* Adds support for sup html tags

* Corrects function description

docs-source/api-python/process-docstring.py

@@ -51,6 +51,12 @@ def process_docstring(app, what, name, obj, options, lines):
                 s = linesep + s
             newline = '.. verbatim::' + linesep
             return newline + '    ' + s.replace(linesep, linesep + '    ')
+    def replace_subscript(m):
+        """ Replace subscript tags. """
+        return r'\ :sub:`{}`\ '.format(m.group(1))
+    def replace_superscript(m):
+        """ Replace superscript tags. """
+        return r'\ :sup:`{}`\ '.format(m.group(1))
 
     linesep = '|LINEBREAK|'
     joined = linesep.join(lines)
@@ -60,6 +66,9 @@ def process_docstring(app, what, name, obj, options, lines):
     joined = re.sub(r'@deprecated(.*?\|LINEBREAK\|)', repl2, joined, flags=re.IGNORECASE)
     joined = re.sub(r'<i>(.*?)</i>', repl3, joined)
     joined = re.sub(r'<verbatim>(.*?)</verbatim>', repl4, joined)
+    joined = re.sub(r'<sub>(.*?)</sub>', replace_subscript, joined)
+    joined = re.sub(r'<sup>(.*?)</sup>', replace_superscript, joined)
+
     lines[:] = [(l if not l.isspace() else '') for l in joined.split(linesep)]
 
 
@@ -68,10 +77,10 @@ def setup(app):
 
 
 def test():
-    lines    = ['Hello World', '<tt><pre>', 'contents', '</pre></tt>', '', '<tt>contents2</tt>']
-    linesRef = ['Hello World', '.. code-block:: c++', '', '    contents', '', '', '.. code-block:: c++', '', '    contents2']
+    lines    = ['Hello World', '<tt><pre>', 'contents', '</pre></tt>', '', '<tt>contents2</tt>', 'r<sub>1</sub>', 'r<sup>1</sup>']
+    linesRef = ['Hello World', '.. code-block:: c++', '', '    contents', '', '', '.. code-block:: c++', '', '    contents2', 'r\\ :sub:`1`\\ ', 'r\\ :sup:`1`\\ ']
     process_docstring(None, None, None, None, None, lines)
-    assert lines == linesRef
+    assert lines == linesRef, (lines, linesRef)
 
 if __name__ == '__main__':
     test()

docs-source/sphinx/autonumber.py

@@ -34,7 +34,7 @@ def chapter_numbers_by_section(env):
         sections = env.toc_secnumbers[doc]
         for section_id in sections:
             # Include the src to disambiguate duplicates
-            src = env.srcdir + "/" + doc
+            src = str(Path(env.srcdir)/doc)
             key = f"{src}:{section_id[1:]}"
             if key in section_numbers:
                 warn(f"{section_id} is duplicated in {src}")

wrappers/python/src/swig_doxygen/swigInputBuilder.py

@@ -17,7 +17,8 @@ except ImportError:
     from HTMLParser import HTMLParser
 
 INDENT = "   "
-docTags = {'emphasis':'i', 'bold':'b', 'itemizedlist':'ul', 'listitem':'li', 'preformatted':'pre', 'computeroutput':'tt', 'subscript':'sub', 'verbatim': 'verbatim'}
+docTags = {'emphasis':'i', 'bold':'b', 'itemizedlist':'ul', 'listitem':'li', 'preformatted':'pre', 'computeroutput':'tt', 
+           'superscript': 'sup', 'subscript':'sub', 'verbatim': 'verbatim'}
 
 def is_method_abstract(argstring):
     return argstring.split(")")[-1].find("=0") >= 0