Fix documentation build on RTD

.rtd_pip_reqs.txt

@@ -1,6 +1,37 @@
-sphinx
-sphinxcontrib-napoleon
-sphinx-markdown-tables
-sphinx-rtd-theme
-recommonmark
-m2r
+# Direct dependencies:
+# Sphinx
+# sphinx-markdown-tables
+# sphinx-rtd-theme
+# sphinxcontrib-napoleon
+# m2r2
+alabaster==0.7.12
+Babel==2.9.1
+certifi==2021.10.8
+charset-normalizer==2.0.7
+docutils==0.17.1
+idna==3.3
+imagesize==1.2.0
+Jinja2==3.0.2
+m2r2==0.3.1
+Markdown==3.3.4
+MarkupSafe==2.0.1
+mistune==0.8.4
+packaging==21.0
+pockets==0.9.1
+Pygments==2.10.0
+pyparsing==3.0.3
+pytz==2021.3
+requests==2.26.0
+six==1.16.0
+snowballstemmer==2.1.0
+Sphinx==4.2.0
+sphinx-markdown-tables==0.0.15
+sphinx-rtd-theme==1.0.0
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-napoleon==0.7
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+urllib3==1.26.7

doc/conf.py

@@ -37,7 +37,7 @@
 extensions = [
     'sphinx.ext.napoleon',
     'sphinx.ext.autodoc',
-    'recommonmark',
+    'm2r2',
     'sphinx.ext.autosummary',
     'sphinx_markdown_tables',
 ]
@@ -78,7 +78,7 @@
 #
 html_theme = 'sphinx_rtd_theme'
 def setup(app):
-    app.add_stylesheet('custom.css')
+    app.add_css_file('custom.css')
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

doc/md2rst.py

@@ -1,4 +1,4 @@
-import m2r
+import m2r2
 import re
 
 
@@ -25,7 +25,7 @@ def absolute_links(txt):
 
 def md2rst(source: str, target: str):
     txt = absolute_links(read(source))
-    txt = m2r.convert(txt)
+    txt = m2r2.convert(txt, anonymous_references=True)
     with open(target, 'w') as f:
         f.write(txt)