Try to switch to myst now that it supports mermaid

https://stackoverflow.com/a/76819611/125507
endolith · Nov 18, 2024 · cc25478 · cc25478
1 parent d608e28
commit cc25478
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 15 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -32,11 +32,11 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.extlinks',
-    'numpydoc',
-    'm2r2',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
     'sphinxcontrib.mermaid',
-    ]
+    'myst_parser'
+]
 
 extlinks = {
     'doi': ('https://dx.doi.org/%s', 'doi:%s'),
@@ -88,3 +88,9 @@ def copy_examples(app, docname):
 
 def setup(app):
     app.connect('build-finished', copy_examples)
+
+# Add this to enable regular markdown mermaid syntax
+myst_fence_as_directive = ["mermaid"]
+
+# Add README.md as the index page
+root_doc = 'index'  # or 'contents' in older versions
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -1 +1,2 @@
-.. mdinclude:: ../examples/README.md
+.. include:: ../examples/README.md
+   :parser: myst_parser.sphinx_
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,13 +1,12 @@
-.. elsim documentation master file, created by
-   sphinx-quickstart on Wed Feb 15 16:14:19 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-.. mdinclude:: ../README.md
+   examples
+   modules
 
 
 

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,9 +1,6 @@
-sphinx<7.0
-docutils==0.16
-mistune==0.8.4
-m2r2
+myst-parser
+sphinxcontrib.mermaid
 -e .
 numpydoc
-sphinxcontrib.mermaid
 sphinx_rtd_theme
 sphinxcontrib-apidoc