docs: fix readthedocs.io configuration

- add `.readthedocs.yaml` configuration file
- use `myst` as the markdown parser
- fix outdated concepts in `conf.py`
- remove debug output from `conf.py`
- add doc requirements for local testing
- add reference to recently added `Hamiltonian` section

.readthedocs.yaml

@@ -0,0 +1,21 @@
+---
+# Read the Docs configuration file for Sphinx projects
+
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: conf.py
+
+
+python:
+  install:
+    - requirements: docs/requirements.txt

conf.py

@@ -46,8 +46,8 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx_markdown_tables', 'sphinx.ext.intersphinx',
-                'sphinx.ext.coverage', 'sphinx.ext.autodoc']
+extensions = ['sphinx_markdown_tables', 'myst_parser',
+              'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.autodoc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -58,25 +58,14 @@
 # source_suffix = ['.rst', '.md']
 # source_suffix = '.md'
 
-source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
-
-
-# from recommonmark.parser import CommonMarkParser
-
-# The suffix of source filenames.
-
-# source_suffix = ['.rst', '.md']
-
-# parsers = {
-#     '.md': CommonMarkParser,
-# }
-
-# from sphinxcontrib.pandoc_markdown import MarkdownParser
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 
-source_suffix = ['.rst', '.md']
-# source_parsers = {
-#    '.md': MarkdownParser,
-# }
+myst_enable_extensions = [
+    'dollarmath',
+]
 
 
 # The master toctree document.
@@ -87,7 +76,7 @@
 
 # General information about the project.
 project = u'Spirit'
-copyright = u'2017, Gideon Mueller and contributors'
+copyright = u'2024, Gideon Mueller and contributors'
 author = u'Gideon Mueller and contributors'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -104,12 +93,19 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['.github', '_build', '../core/docs/python-api/spirit.rst', 'Thumbs.db', '.DS_Store']
+exclude_patterns = [
+    '.venv',
+    '.github',
+    '_build',
+    '../core/docs/python-api/spirit.rst',
+    'Thumbs.db',
+    '.DS_Store',
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -212,7 +208,7 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/', None)}
 
 
 def run_apidoc(_):
@@ -244,14 +240,33 @@ def run_apidoc(_):
     build_dir = os.path.join(source_dir, 'build')
     if not os.path.exists(build_dir):
         os.mkdir(build_dir)
-    subprocess.check_call(['cmake', '..', '-DSPIRIT_BUILD_FOR_CXX=OFF', '-DSPIRIT_SKIP_HTST=ON'], cwd=build_dir)
+    subprocess.check_call([
+            'cmake',
+            '..',
+            '-DSPIRIT_BUILD_FOR_CXX=OFF',
+            '-DSPIRIT_BUILD_TEST=ON',
+            '-DSPIRIT_SKIP_HTST=ON',
+        ],
+        cwd=build_dir
+    )
     subprocess.check_call(['make'], cwd=build_dir)
 
     # See https://stackoverflow.com/a/30144019
     env = os.environ.copy()
-    env["SPHINX_APIDOC_OPTIONS"] = 'members,special-members,private-members,undoc-members,show-inheritance'
+    env["SPHINX_APIDOC_OPTIONS"] = ','.join(
+        [
+            'members',
+            'special-members',
+            'private-members',
+            'undoc-members',
+            'show-inheritance',
+        ]
+    )
     subprocess.check_call([cmd_path] + options, env=env)
 
+    if not os.path.exists(apidoc_dir):
+        os.mkdir(apidoc_dir)
+
     #####################
     with open(os.path.join(apidoc_dir, 'parameters.rst'), "w") as parameters_file:
         parameters_file.write("spirit.parameters\n==================================\n\n")
@@ -266,21 +281,5 @@ def run_apidoc(_):
         with open(os.path.join(apidoc_dir, 'spirit.parameters.mmf.rst'), 'r') as generated_file:
             parameters_file.write(generated_file.read())
 
-    print("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
-    print("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
-    testfile = os.path.join(apidoc_dir, 'spirit.log.rst')
-    with open(testfile, 'r') as f:
-        print(f.read())
-    print("yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy")
-    print("yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy")
-    testfile = os.path.join(apidoc_dir, 'spirit.geometry.rst')
-    with open(testfile, 'r') as f:
-        print(f.read())
-    print("zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz")
-    print("zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz")
-
-    if not os.path.exists(apidoc_dir):
-        os.mkdir(apidoc_dir)
-
 def setup(app):
-    app.connect('builder-inited', run_apidoc)
+    app.connect('builder-inited', run_apidoc)

docs/index.rst

@@ -19,6 +19,7 @@ Spirit - Spin Simulation Framework
     Input file specification     <../core/docs/Input>
     Definitions                  <../core/docs/Definitions>
     Additional features          <../core/docs/Features>
+    Hamiltonian                  <../core/docs/Hamiltonian>
 
 .. toctree::
     :maxdepth: 2
@@ -58,4 +59,4 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+* :ref:`search`

docs/requirements-local.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinx_rtd_theme

docs/requirements.txt

@@ -1,5 +1,6 @@
 pandoc
 sphinx-markdown-tables
+myst-parser
 numpy
 cmake
 gcc7