Merge pull request #99 from dihm/rtd_update

Modernize RTD build

Author: dihm

docs/source/conf.py

@@ -13,8 +13,6 @@
 import copy
 import os
 from pathlib import Path
-from m2r import MdInclude
-from recommonmark.transform import AutoStructify
 from jinja2 import FileSystemLoader, Environment
 
 # -- Project information (unique to each project) -------------------------------------
@@ -47,7 +45,7 @@
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx_rtd_theme",
-    "recommonmark",
+    "myst_parser",
 ]
 
 autodoc_typehints = 'description'
@@ -73,6 +71,7 @@
 
 # Prefix each autosectionlabel with the name of the document it is in and a colon
 autosectionlabel_prefix_document = True
+myst_heading_anchors = 2
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -211,23 +210,8 @@
 # Customize the html_theme
 html_theme_options = {'navigation_depth': 3}
 
-# Use m2r only for mdinclude and recommonmark for everything else
-# https://github.com/readthedocs/recommonmark/issues/191#issuecomment-622369992
 def setup(app):
-    config = {
-        # 'url_resolver': lambda url: github_doc_root + url,
-        'auto_toc_tree_section': 'Contents',
-        'enable_eval_rst': True,
-    }
-    app.add_config_value('recommonmark_config', config, True)
-    app.add_transform(AutoStructify)
-
-    # from m2r to make `mdinclude` work
-    app.add_config_value('no_underscore_emphasis', False, 'env')
-    app.add_config_value('m2r_parse_relative_links', False, 'env')
-    app.add_config_value('m2r_anonymous_references', False, 'env')
-    app.add_config_value('m2r_disable_inline_math', False, 'env')
-    app.add_directive('mdinclude', MdInclude)
+    
     app.add_css_file('custom.css')
 
     # generate the components.rst file dynamically so it points to stable/latest

readthedocs.yaml

@@ -4,6 +4,12 @@
 # Required
 version: 2
 
+# Set build environment options
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   builder: dirhtml
@@ -15,13 +21,11 @@ formats:
   - pdf
   - epub
 
-# Optionally set the version of Python and requirements required to build your docs
+# Optionally set the requirements required to build your docs
 python:
-   version: 3.7
    install:
       - method: pip
         path: .
         extra_requirements:
             - docs
-   system_packages: true
 

setup.cfg

@@ -41,11 +41,9 @@ install_requires =
 [options.extras_require]
 docs = 
   PyQt5
-  Sphinx==4.4.0
-  sphinx-rtd-theme==0.5.2
-  recommonmark==0.6.0
-  m2r==0.2.1
-  mistune<2.0.0
+  Sphinx==7.2.6
+  sphinx-rtd-theme==2.0.0
+  myst_parser==2.0.0
 
 [options.package_data]
 labscript_profile = ../labscript-suite.pth