Add custom css/js, move to myst-nb and add notebook support

Author: timkpaine

.gitignore

@@ -130,6 +130,7 @@ docs/_build/
 docs/api
 docs/index.md
 docs/html
+docs/jupyter_execute
 index.md
 _template/labextension
 

docs/notebooks/example.ipynb

@@ -0,0 +1,52 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Example Notebook\n",
+    "This is an example notebook."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "hello world!\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\"hello world!\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3.11 (XPython)",
+   "language": "python",
+   "name": "xpython"
+  },
+  "language_info": {
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "version": "3.11.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/src/configuration.md

@@ -129,3 +129,31 @@ autodoc_pydantic_model_show_json = true
 autodoc_pydantic_settings_show_json = false
 autodoc_pydantic_model_show_field_summary = false
 ```
+
+## Myst-NB
+
+```toml
+[tool.yardang]
+jupyter_execute_notebooks = "off"
+execution_excludepatterns = []
+```
+
+Notebooks can be included with:
+
+````raw
+```{eval-rst}
+.. toctree::
+  :maxdepth: 1
+
+  ../notebooks/example
+```
+````
+
+An example follows:
+
+```{eval-rst}
+.. toctree::
+  :maxdepth: 1
+
+  ../notebooks/example
+```

pyproject.toml

@@ -27,7 +27,7 @@ classifiers = [
 dependencies = [
     "autodoc-pydantic",
     "furo",
-    "myst-parser",
+    "myst-nb",
     "packaging",
     "rich",
     "sphinx>=7.2.6,<8.1",
@@ -77,7 +77,7 @@ replace = 'version = "{new_version}"'
 ignore = [
     ".copier-answers.yml",
     "docs/*",
-    "docs/src/*",
+    "docs/**/*",
     "Makefile",
     "setup.py",
 ]

yardang/build.py

@@ -6,26 +6,7 @@
 from typing import List, Optional
 from .utils import get_config
 
-__all__ = (
-    "generate_docs_configuration",
-    "CUSTOM_CSS",
-)
-
-# Wider screen for furo
-CUSTOM_CSS = """
-/* Wide main page */
-.content {
-    flex: 1;
-}
-aside.sidebar-drawer {
-    width: unset;
-}
-
-/* Left-align tables */
-article table.align-default {
-    margin-left: 0;
-}
-"""
+__all__ = ("generate_docs_configuration",)
 
 
 @contextmanager
@@ -44,6 +25,8 @@ def generate_docs_configuration(
     cname: str = "",
     pages: Optional[List] = None,
     use_autoapi: Optional[bool] = None,
+    custom_css: Optional[Path] = None,
+    custom_js: Optional[Path] = None,
 ):
     if os.path.exists("conf.py"):
         # yield folder path to sphinx build
@@ -80,9 +63,15 @@ def generate_docs_configuration(
         cname = cname or get_config(section="cname")
         pages = pages or get_config(section="pages") or []
         use_autoapi = use_autoapi or get_config(section="use-autoapi")
+
+        custom_css = custom_css or get_config(section="custom-css") or (Path(__file__).parent / "custom.css")
+        custom_js = custom_js or get_config(section="custom-js") or (Path(__file__).parent / "custom.js")
+
         source_dir = os.path.curdir
-        autodoc_pydantic_args = {}
+
+        configuration_args = {}
         for f in (
+            # autodoc/autodoc-pydantic
             "autodoc_pydantic_model_show_config_summary",
             "autodoc_pydantic_model_show_validator_summary",
             "autodoc_pydantic_model_show_validator_members",
@@ -92,10 +81,20 @@ def generate_docs_configuration(
             "autodoc_pydantic_model_show_json",
             "autodoc_pydantic_settings_show_json",
             "autodoc_pydantic_model_show_field_summary",
+            # myst/myst-nb
+            "jupyter_execute_notebooks",
+            "execution_excludepatterns",
         ):
-            default_value = {"autodoc_pydantic_model_member_order": '"bysource"', "autodoc_pydantic_model_show_json": True}.get(f, False)
+            default_value = {
+                # autodoc/autodoc-pydantic
+                "autodoc_pydantic_model_member_order": '"bysource"',
+                "autodoc_pydantic_model_show_json": True,
+                # myst/myst-nb
+                "execution_excludepatterns": [],
+                "jupyter_execute_notebooks": "off",
+            }.get(f, False)
             config_value = get_config(section=f"{f}")
-            autodoc_pydantic_args[f] = default_value if config_value is None else config_value
+            configuration_args[f] = default_value if config_value is None else config_value
         # create a temporary directory to store the conf.py file in
         with TemporaryDirectory() as td:
             templateEnv = Environment(loader=FileSystemLoader(searchpath=str(Path(__file__).parent.resolve())))
@@ -115,12 +114,18 @@ def generate_docs_configuration(
                 pages=pages,
                 use_autoapi=use_autoapi,
                 source_dir=source_dir,
-                **autodoc_pydantic_args,
+                **configuration_args,
             )
             # dump to file
             template_file = Path(td) / "conf.py"
             template_file.write_text(template)
 
+            # write custom css and customjs
+            Path("docs/html/_static/styles").mkdir(parents=True, exist_ok=True)
+            Path("docs/html/_static/styles/custom.css").write_text(custom_css.read_text())
+            Path("docs/html/_static/js").mkdir(parents=True, exist_ok=True)
+            Path("docs/html/_static/js/custom.js").write_text(custom_js.read_text())
+
             # append docs-specific ignores to gitignore
             if Path(".gitignore").exists():
                 has_html_build_folder = False

yardang/cli.py

@@ -1,19 +1,12 @@
 from sys import executable
-from pathlib import Path
 from subprocess import Popen, PIPE
 from typer import Typer
 
-from .build import generate_docs_configuration, CUSTOM_CSS
+from .build import generate_docs_configuration
 
 
 def build(quiet: bool = False, debug: bool = False):
     with generate_docs_configuration() as file:
-        folder = Path("docs/html/_static/styles")
-        css = folder / "custom.css"
-        if not css.exists():
-            folder.mkdir(parents=True, exist_ok=True)
-            css.write_text(CUSTOM_CSS)
-
         build_cmd = [
             executable,
             "-m",

yardang/conf.py.j2

@@ -29,8 +29,7 @@ use_autoapi = {{use_autoapi}}  # noqa: F821
 # Standardized below #
 ######################
 extensions = [
-    "myst_parser",
-    "sphinx.ext.viewcode",
+    "myst_nb",
     "sphinx.ext.napoleon",
     "sphinx_design",
     "sphinx_copybutton",
@@ -41,7 +40,19 @@ extensions = [
 ]
 if use_autoapi in (True, None):
     # add if it is set to true or if it is set to None
-    extensions.append("autoapi.extension")
+    # NOTE: bug in autoapi that requires
+    # viewcode to come after
+    extensions.extend([
+        "autoapi.extension",
+        "sphinx.ext.viewcode",
+    ])
+else:
+    # NOTE: bug in autoapi that requires
+    # viewcode to come after
+    extensions.append([
+        "sphinx.ext.viewcode",
+    ])
+
 
 os.environ["SPHINX_BUILDING"] = "1"
 html_theme = "{{theme}}"
@@ -50,19 +61,32 @@ html_static_path = []
 html_css_files = [
     "styles/custom.css",
 ]
+html_js_files = [
+    "js/custom.js",
+]
+
 master_doc = "index"
 templates_path = ["_templates"]
 source_suffix = [".rst", ".md"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "node_modules", "_skbuild", ".pytest_cache", "js/*"]
 language = "en"
 pygments_style = "sphinx"
+
+# myst / myst-nb
+myst_enable_extensions = ["colon_fence"]
+jupyter_execute_notebooks = "{{jupyter_execute_notebooks}}"
+execution_excludepatterns = {{execution_excludepatterns}}
+
+# autosummary
 autosummary_generate = True
+
+# autoapi
 autoapi_dirs = [module]
 autoapi_python_class_content = "both"
-myst_enable_extensions = ["colon_fence"]
-autodoc_default_options = {
-    "show-inheritance": True,
-}
+autoapi_add_toctree_entry = use_autoapi is True
+
+# autodoc/autodoc-pydantic
+autodoc_default_options = {"show-inheritance": True}
 autodoc_pydantic_model_show_config_summary = {{autodoc_pydantic_model_show_config_summary}}  # noqa: F821
 autodoc_pydantic_model_show_validator_summary = {{autodoc_pydantic_model_show_validator_summary}}  # noqa: F821
 autodoc_pydantic_model_show_validator_members = {{autodoc_pydantic_model_show_validator_members}}  # noqa: F821
@@ -71,7 +95,7 @@ autodoc_pydantic_field_show_constraints = {{autodoc_pydantic_field_show_constrai
 autodoc_pydantic_model_member_order = {{autodoc_pydantic_model_member_order}}  # noqa: F821
 autodoc_pydantic_model_show_json = {{autodoc_pydantic_model_show_json}}  # noqa: F821
 autodoc_pydantic_settings_show_json = {{autodoc_pydantic_settings_show_json}}  # noqa: F821
-autoapi_add_toctree_entry = use_autoapi is True
+
 toctree_base = """{toctree}
 ---
 caption: ""
@@ -94,36 +118,12 @@ def run_copycname(_):
     if cname:
         out.write_text(cname)
 
-def run_create_version_marker_to_be_committed(_):
+def run_create_previous_version_markdown(_):
     versions_folder = Path("{{source_dir}}") / "docs" / "versions"
     if not versions_folder.exists():
         versions_folder.mkdir(parents=True, exist_ok=True)
-    version_file = versions_folder / f"{version}.txt"
-    version_file.write_text("commit this file to ensure these docs can be referenced in the future")
-
-def run_create_older_version_docs(_):
-    versions_folder = Path("{{source_dir}}") / "docs" / "versions"
-    if not versions_folder.exists():
-        # no older versions yet
-        return
-    all_versions = [f.replace(".txt", "") for f in os.listdir(str(versions_folder)) if f.endswith(".txt")]
-    all_versions_as_versions = []
-    invalid_version = Version("999.999.999")
-    for version in all_versions:
-        try:
-            all_versions_as_versions.append(Version(version))
-        except BaseException:
-            all_versions_as_versions.append(invalid_version)
-    all_versions_as_versions.sort(reverse=True)
-    out = Path("{{source_dir}}") / "docs" / "versions" / "versions.md"
-    out.write_text("# Previous Versions\n\n")
-    for i, older_version in enumerate(all_versions_as_versions):
-        if older_version != invalid_version and str(older_version) in all_versions:
-            older_version_literal = str(older_version)
-            with out.open("a") as outfile:
-                outfile.write(f"- [{older_version_literal}]({docs_host_root}/{name}/{older_version_literal}/)\n")
-    with out.open("a") as outfile:
-        outfile.write("\n")
+    version_file = versions_folder / "version.md"
+    version_file.write_text("# Previous Versions")
 
 def run_add_version_links_to_toctree(app, doctree):
     from sphinx.addnodes import toctree
@@ -148,8 +148,7 @@ def run_add_version_links_to_toctree(app, doctree):
             nodes[-1]["includefiles"].append(toc_entry)
 
 def setup(app):
-    {# app.connect("builder-inited", run_create_older_version_docs) #}
-    {# app.connect("builder-inited", run_create_version_marker_to_be_committed) #}
+    {# app.connect("builder-inited", run_create_previous_version_markdown) #}
     app.connect("builder-inited", run_copyreadme)
     app.connect("builder-inited", run_copycname)
     {# app.connect("doctree-read", run_add_version_links_to_toctree, priority=500) #}

yardang/custom.css

@@ -0,0 +1,12 @@
+/* Wide main page */
+.content {
+    flex: 1;
+}
+aside.sidebar-drawer {
+    width: unset;
+}
+
+/* Left-align tables */
+article table.align-default {
+    margin-left: 0;
+}

yardang/custom.js

@@ -0,0 +1 @@
+// TODO