doc: m2r2->myst

.gitignore

@@ -113,5 +113,5 @@ venv.bak/
 *.swp
 
 _untracked
-doc/_static/README.rst
+doc/_generated/
 doc/build/

.rtd_pip_reqs.txt

@@ -1,11 +1,10 @@
 # Direct dependencies:
+# myst-parser
 # Sphinx
-# sphinx-markdown-tables
 # sphinx-reredirects
 # sphinx-rtd-theme
 # sphinxcontrib-bibtex
 # sphinxcontrib-napoleon
-# m2r2
 alabaster==1.0.0
 babel==2.17.0
 certifi==2025.7.9
@@ -18,11 +17,12 @@ idna==3.10
 imagesize==1.4.1
 Jinja2==3.1.6
 kiwisolver==1.4.8
-m2r2==0.3.4
-Markdown==3.8.2
+markdown-it-py==3.0.0
 MarkupSafe==3.0.2
 matplotlib==3.10.3
-mistune==0.8.4
+mdit-py-plugins==0.5.0
+mdurl==0.1.2
+myst-parser==4.0.1
 numpy==2.3.1
 packaging==25.0
 pandas==2.3.1
@@ -32,13 +32,12 @@ Pygments==2.19.2
 pyparsing==3.2.3
 python-dateutil==2.9.0.post0
 pytz==2025.2
+pyyaml==6.0.2
 requests==2.32.4
 roman-numerals-py==3.1.0
-setuptools==80.9.0
 six==1.17.0
 snowballstemmer==3.0.1
 Sphinx==8.2.3
-sphinx-markdown-tables==0.0.17
 sphinx-reredirects==1.0.0
 sphinx-rtd-theme==3.0.2
 sphinxcontrib-applehelp==2.0.0
@@ -52,4 +51,3 @@ sphinxcontrib-qthelp==2.0.0
 sphinxcontrib-serializinghtml==2.0.0
 tzdata==2025.2
 urllib3==2.5.0
-wheel==0.45.1

doc/conf.py

@@ -27,7 +27,11 @@
 
 import subprocess
 
-subprocess.run(['python', 'md2rst.py'])
+subprocess.run(
+    [sys.executable, 'prepare_readme.py'],
+    cwd=os.path.dirname(os.path.abspath(__file__)),
+    check=True,
+)
 
 # -- General configuration ---------------------------------------------------
 
@@ -37,9 +41,8 @@
 extensions = [
     'sphinx.ext.napoleon',
     'sphinx.ext.autodoc',
-    'm2r2',
+    'myst_parser',
     'sphinx.ext.autosummary',
-    'sphinx_markdown_tables',
     'sphinx_reredirects',
     # bibtex references
     "sphinxcontrib.bibtex",
@@ -51,7 +54,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['build/doctrees', 'build/html']
+exclude_patterns = ['build/doctrees', 'build/html', '_generated']
 
 master_doc = 'index'
 

doc/index.rst

@@ -1,5 +1,5 @@
-.. include::
-   _static/README.rst
+.. include:: _generated/README.md
+   :parser: myst_parser.sphinx_
 
 .. toctree::
    :maxdepth: 3

doc/md2rst.py → doc/prepare_readme.py

@@ -1,5 +1,6 @@
-import m2r2
+"""Prepare README.md for inclusion in the Sphinx documentation."""
 import re
+from pathlib import Path
 
 
 def read(fname):
@@ -9,10 +10,10 @@
 
 def absolute_links(txt):
     """Replace relative petab github links by absolute links."""
-    raw_base = "(https://raw.githubusercontent.com/petab-dev/petab/master/"
-    embedded_base = "(https://github.com/petab-dev/petab/tree/master/"
+    raw_base = "(https://raw.githubusercontent.com/petab-dev/petab/main/"
+    embedded_base = "(https://github.com/petab-dev/petab/blob/main/"
     # iterate over links
     for var in re.findall(r'\[.*?\]\((?!http).*?\)', txt):
         if re.match(r'.*?.(png|svg)\)', var):
             # link to raw file
             rep = var.replace("(", raw_base)
@@ -23,13 +24,12 @@
     return txt
 
 
-def md2rst(source: str, target: str):
+def prepare_readme(source: str, target: str):
     txt = absolute_links(read(source))
-    txt = m2r2.convert(txt, anonymous_references=True)
+    Path(target).parent.mkdir(parents=True, exist_ok=True)
     with open(target, 'w') as f:
         f.write(txt)
 
 
 if __name__ == '__main__':
-    # parse readme
-    md2rst('../README.md', '_static/README.rst')
+    prepare_readme('../README.md', '_generated/README.md')