upgrade Sphinx, add Markdown support #10101 #10111

We don't seem to be using intersphinx and I got an error about it so i
simply removed it.

I also got rid of the Python 3.10 vs 3.11 divide. It's no longer
relevant and some older servers were holding us back. Everyone should
use the same (latest!) Sphinx.

I included a tiny conclusion.md file as a demo, but it can be removed,
of course.

doc/sphinx-guides/requirements.txt

@@ -1,12 +1,7 @@
-# Developers, please use Python 3.9 or lower to build the guides.
-# For your convenience, a solution for Python 3.10 is provided below
-# but we would prefer that you use the same version of Sphinx
-# (below on the < 3.10 line) that is used to build the production guides.
-Sphinx==3.5.4 ; python_version < '3.10'
-Sphinx==5.3.0 ; python_version >= '3.10'
+Sphinx==7.2.6
 
-# Necessary workaround for ReadTheDocs for Sphinx 3.x - unnecessary as of Sphinx 4.5+
-Jinja2>=3.0.2,<3.1
-
-# Sphinx - Additional modules
+# inline icons
 sphinx-icon==0.1.2
+
+# Markdown support
+myst-parser==2.0.0

doc/sphinx-guides/source/conf.py

@@ -38,11 +38,11 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.intersphinx',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.graphviz',
     'sphinxcontrib.icon',
+    'myst_parser',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -430,9 +430,6 @@
 # If false, no index is generated.
 #epub_use_index = True
 
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
 # Suppress "WARNING: unknown mimetype for ..." https://github.com/IQSS/dataverse/issues/3391
 suppress_warnings = ['epub.unknown_project_files']
 rst_prolog = """

doc/sphinx-guides/source/qa/conclusion.md

@@ -0,0 +1,11 @@
+Conclusion
+==========
+
+QA is awesome. Do you know what else is awesome? Markdown.
+
+It's easy to create a [link](https://dataverse.org), for example, and nested bullets don't need extra indentation:
+
+- foo
+  - one
+  - two
+- bar

doc/sphinx-guides/source/qa/index.rst

@@ -11,12 +11,4 @@ QA Guide
    manual-testing
    test-automation-integration
    other-approaches
-
-
-
-
-
-
-
-
-
+   conclusion