Swithch docs tutorial generation to myst_nb, shows note/warning box…

…es etc, and update version number in `conf.py`
WMD-group · Feb 8, 2024 · 810c20c · 810c20c
1 parent 7a595f3
commit 810c20c
Show file tree

Hide file tree

Showing 7 changed files with 37 additions and 13 deletions.
diff --git a/docs/source/PyTASER_DFT_Example.ipynb b/docs/source/PyTASER_DFT_Example.ipynb
@@ -0,0 +1 @@
+../../examples/PyTASER_DFT_Example.ipynb
diff --git a/docs/source/PyTASER_MP_Example.ipynb b/docs/source/PyTASER_MP_Example.ipynb
@@ -0,0 +1 @@
+../../examples/PyTASER_MP_Example.ipynb
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -13,6 +13,8 @@
 import os
 import sys
 
+from recommonmark.transform import AutoStructify
+
 sys.path.insert(0, os.path.abspath("../../"))
 # from pytaser import __version__
 
@@ -24,7 +26,7 @@
 author = "Savyasanchi Aggarwal"
 
 # The full version, including alpha/beta/rc tags
-release = "2.0.0"
+release = "2.3.0"
 
 # -- General configuration ---------------------------------------------------
 
@@ -40,8 +42,16 @@
     "sphinx.ext.napoleon",
     "sphinx_copybutton",
     "sphinx_toggleprompt",
-    "nbsphinx",
-    "nbsphinx_link",
+    "myst_nb",  # for jupyter notebooks
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".ipynb": "myst-nb",
+}
+
+myst_enable_extensions = [
+    "html_admonition",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -93,11 +103,29 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3.6", None),
+    "python": ("https://docs.python.org/3.10", None),
     "numpy": ("http://docs.scipy.org/doc/numpy/", None),
     "pymatgen": ("http://pymatgen.org/", None),
     "matplotlib": ("http://matplotlib.org", None),
 }
 
 # -- Options for autodoc -----------------------------------------------------
 autoclass_content = "both"
+
+# -- Options for nb extension -----------------------------------------------
+nb_execution_mode = "off"
+myst_heading_anchors = 2
+github_doc_root = "https://github.com/executablebooks/MyST-Parser/tree/master/docs/"
+
+
+def setup(app):
+    """Add configuration for MyST parser."""
+    app.add_config_value(
+        "myst_parser_config",
+        {
+            "url_resolver": lambda url: github_doc_root + url,
+            "auto_toc_tree_section": "Contents",
+        },
+        True,
+    )
+    app.add_transform(AutoStructify)
diff --git a/docs/source/dft_examples.nblink b/docs/source/dft_examples.nblink
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -173,8 +173,8 @@ Liam Harnett-Caulfield.
    :caption: Usage Guide
    :hidden:
 
-   dft_examples
-   mp_example
+   PyTASER_DFT_Example
+   PyTASER_MP_Example
 
 
 .. toctree::

diff --git a/docs/source/mp_example.nblink b/docs/source/mp_example.nblink
diff --git a/examples/PyTASER_DFT_Example.ipynb b/examples/PyTASER_DFT_Example.ipynb
@@ -419,7 +419,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## CH$_3$NH$_3$PbI$_3$ (MAPI) with spin-orbit coupling (SOC)"
+    "## CH₃NH₃PbI₃ (MAPI) with spin-orbit coupling (SOC)"
    ]
   },
   {