neuromatch-course-kit 0.1.1__py3-none-any.whl

neuromatch_course_kit-0.1.1.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.5
+Name: neuromatch-course-kit
+Version: 0.1.1
+Summary: Neuromatch course kit: notebook generation, content checks and site preparation for MyST courses
+Project-URL: Homepage, https://github.com/neuromatch/course-kit
+Project-URL: Issues, https://github.com/neuromatch/course-kit/issues
+License-Expression: BSD-3-Clause
+Requires-Python: >=3.10
+Requires-Dist: ipykernel
+Requires-Dist: jupytext>=1.16
+Requires-Dist: mystmd==1.11.0
+Requires-Dist: nbclient
+Requires-Dist: nbformat
+Requires-Dist: pyyaml
+Provides-Extra: test
+Requires-Dist: ipywidgets; extra == 'test'
+Requires-Dist: matplotlib; extra == 'test'
+Requires-Dist: numpy; extra == 'test'
+Requires-Dist: playwright; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-rerunfailures; extra == 'test'
+Description-Content-Type: text/markdown
+
+# neuromatch-course-kit
+
+The `nma-kit` command line tool for Neuromatch MyST courses: notebook
+generation, content checks and site preparation. See the
+[course kit repository](https://github.com/neuromatch/course-kit) for docs.

neuromatch_course_kit-0.1.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+nma_kit/__init__.py,sha256=5a4Jy2tMbpaFNiZHNTjEexm_fHtPEgQVUuD8SDIqvRQ,128
+nma_kit/cells.py,sha256=-KbtcZOEzZSStJoz1gBUVt4wUk172b8HbJAlehf7BoU,962
+nma_kit/cli.py,sha256=v6mz_a9UA9V8xpN7i6xVr2_If9A5bxxGKlcMzrjr2N4,4898
+nma_kit/config.py,sha256=qyPOWFe9jlQPJTrUCWBqe7zkF5i4IrczHf3LKVtWX94,3284
+nma_kit/convert.py,sha256=ZJ4jeT8lkG0FKkzfwsCrINgQN5pGaUMbG6ABDVvVZxc,17872
+nma_kit/feedback.py,sha256=Mdc0-NjX5upBjmTfRF_vRofrVBHSMUUeBGKuSjLKhZM,8861
+nma_kit/media.py,sha256=48iANcTXztZD-amd-ENDzrigr9Zv__VLkG6qejKW2Rc,8911
+nma_kit/pin.py,sha256=7NFUF5P0FksiO5Z1xv6-Zce8q-f1qraV1_awDlbpryQ,715
+nma_kit/publish.py,sha256=aydvCvnAysjtJp72eUhHnOx6Sq6BwkZ2-TZFncdq7lo,2651
+nma_kit/scrolly.py,sha256=nFmQMBpzm_K1sceNgRJi9TQsajID7M50EqLHUKfHURs,18385
+nma_kit/solutions.py,sha256=X4YCNkxm-iMnPfn3jkccqkBq6MHeHpmxY9uKtpU-bo8,16422
+neuromatch_course_kit-0.1.1.dist-info/METADATA,sha256=SS5WzRBB8UBXgJWEnZ6tW5uI9UxcZ4_RsXyFo4fwYxc,1065
+neuromatch_course_kit-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+neuromatch_course_kit-0.1.1.dist-info/entry_points.txt,sha256=xlXXMTh2H8cUiIUPt59sm32FGGwJBx6qiAx8LdGSFpY,45
+neuromatch_course_kit-0.1.1.dist-info/RECORD,,

neuromatch_course_kit-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

neuromatch_course_kit-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nma-kit = nma_kit.cli:main

nma_kit/__init__.py

@@ -0,0 +1,3 @@
+"""Neuromatch course kit: notebooks, content checks and site preparation."""
+
+__version__ = "0.1.1"  # x-release-please-version

nma_kit/cells.py

@@ -0,0 +1,28 @@
+"""Editable cells: the `runtime:` frontmatter key (Python side).
+
+`runtime_of` has a JavaScript twin, `runtimeOf` in js/src/cells/src/model.mjs.
+Both are tested against tests/fixtures/cells/runtime.json.
+"""
+
+import re
+
+from nma_kit import scrolly as nma_scrolly
+
+RUNTIMES = ("browser", "colab")
+RUNTIME_RE = re.compile(r"""^runtime:\s*(['"]?)([A-Za-z]+)\1\s*(#.*)?$""", re.M)
+
+
+def runtime_of(text: str) -> str:
+    """'browser' (default) or 'colab' (or the raw invalid value, for validate())."""
+    m = RUNTIME_RE.search(nma_scrolly.frontmatter_text(text))
+    return m.group(2) if m else "browser"
+
+
+def validate(text: str) -> list[str]:
+    errors = []
+    runtime = runtime_of(text)
+    if runtime not in RUNTIMES:
+        errors.append(f"runtime: {runtime!r} must be one of {', '.join(RUNTIMES)}")
+    if runtime == "colab" and nma_scrolly.is_scrolly(text):
+        errors.append("runtime: colab can't be combined with layout: scrolly")
+    return errors

nma_kit/cli.py

@@ -0,0 +1,138 @@
+"""`nma-kit`: the course kit's command line. Run it from the course root.
+
+  nma-kit check                  validate content and myst.yml
+  nma-kit notebooks [--dry-run]  generate student/instructor notebooks and solution files
+  nma-kit render-scrolly         pre-render scrolly page outputs into _build/scrolly/
+  nma-kit prepare-site           add badges + fallback cells to the .md pages and pin the
+                                 kit URL in myst.yml (CI only, never commit the result)
+  nma-kit publish-notebooks      push notebooks/ to the notebooks branch
+
+Exit codes: 0 ok, 1 content problems, 2 usage or configuration errors.
+"""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from nma_kit import __version__
+from nma_kit import convert, scrolly
+from nma_kit.config import MYST_CONFIG, MissingConfig, read_settings
+from nma_kit.pin import pin_kit_url
+from nma_kit.publish import PublishError, publish_notebooks
+
+
+class UsageError(Exception):
+    pass
+
+
+def _validate(check_injected: bool) -> bool:
+    errors = convert.validate_content(check_injected=check_injected)
+    if errors:
+        print("Content rule violations:", file=sys.stderr)
+        for error in errors:
+            print(f"  - {error}", file=sys.stderr)
+    return not errors
+
+
+def _settings():
+    settings = read_settings()
+    try:
+        convert.require_github_repo(settings)
+    except ValueError as exc:
+        raise UsageError(str(exc)) from exc
+    return settings
+
+
+def cmd_check(args) -> int:
+    read_settings()
+    if not _validate(check_injected=True):
+        return 1
+    print("No content problems found.")
+    return 0
+
+
+def cmd_notebooks(args) -> int:
+    settings = _settings()
+    if not _validate(check_injected=True):
+        return 1
+    count = convert.process_tutorials(settings, args.dry_run, prepare_site=False)
+    print(f"Done. Processed {count} file(s).")
+    return 0
+
+
+def cmd_render_scrolly(args) -> int:
+    return scrolly.render_all(read_settings().tutorials_dir)
+
+
+def cmd_prepare_site(args) -> int:
+    settings = _settings()
+    if not _validate(check_injected=False):
+        return 1
+    count = convert.process_tutorials(settings, args.dry_run, prepare_site=True)
+    if not args.dry_run:
+        text = MYST_CONFIG.read_text(encoding="utf-8")
+        pinned = pin_kit_url(text, args.kit_version)
+        if pinned != text:
+            MYST_CONFIG.write_text(pinned, encoding="utf-8")
+            print(f"Pinned course kit URLs in {MYST_CONFIG} to {args.kit_version}")
+    print(f"Done. Prepared {count} page(s).")
+    return 0
+
+
+def cmd_publish_notebooks(args) -> int:
+    settings = read_settings()
+    src = Path("notebooks")
+    if not src.is_dir():
+        raise UsageError("notebooks/ not found: run `nma-kit notebooks` first")
+    message = args.message or "chore: regenerate notebooks" + (
+        f" from {os.environ['GITHUB_SHA'][:12]}" if os.environ.get("GITHUB_SHA") else "")
+    pushed = publish_notebooks(src, settings.notebooks_branch, args.remote, message)
+    print(f"Pushed notebooks to {settings.notebooks_branch}." if pushed else "No notebook changes to push.")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="nma-kit", description="Neuromatch course kit")
+    parser.add_argument("--version", action="version", version=f"nma-kit {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("check", help="validate content and myst.yml").set_defaults(func=cmd_check)
+
+    p = sub.add_parser("notebooks", help="generate notebooks and solution files")
+    p.add_argument("--dry-run", action="store_true")
+    p.set_defaults(func=cmd_notebooks)
+
+    sub.add_parser("render-scrolly", help="pre-render scrolly pages").set_defaults(func=cmd_render_scrolly)
+
+    p = sub.add_parser("prepare-site", help="prepare the .md pages for `myst build` (CI only)")
+    p.add_argument("--dry-run", action="store_true")
+    p.add_argument("--kit-version", default=__version__,
+                   help="version to pin course-kit URLs in myst.yml to (default: this CLI's)")
+    p.set_defaults(func=cmd_prepare_site)
+
+    p = sub.add_parser("publish-notebooks", help="push notebooks/ to the notebooks branch")
+    p.add_argument("--remote", default="origin")
+    p.add_argument("--message", default=None)
+    p.set_defaults(func=cmd_publish_notebooks)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_usage(sys.stderr)
+        return 2
+    try:
+        return args.func(args)
+    except (MissingConfig, UsageError) as exc:
+        print(f"nma-kit: {exc}", file=sys.stderr)
+        return 2
+    except PublishError as exc:
+        print(f"nma-kit: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nma_kit/config.py

@@ -0,0 +1,100 @@
+"""
+Course settings, read from the course's myst.yml.
+
+Kit settings live in the top-level `nma:` block, as `section: {key: value}`
+with string values. js/src/shared/config.mjs reads the same block with a
+YAML parser too; both sides are tested against tests/fixtures/config/settings.json.
+
+New settings (all optional, defaults are the template's conventions):
+
+    nma:
+      paths:
+        tutorials: tutorials        # where the course's .md pages live
+      notebooks:
+        branch: notebooks-branch    # where generated notebooks are published
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+
+import yaml
+
+DEFAULT_TUTORIALS_DIR = "tutorials"
+DEFAULT_NOTEBOOKS_BRANCH = "notebooks-branch"
+NOTEBOOKS_DIR = "notebooks"
+MYST_CONFIG = Path("myst.yml")
+
+GITHUB_RE = re.compile(r"github\.com/([^\s'\"]+?)/?$")
+
+
+class MissingConfig(Exception):
+    """The course's myst.yml does not exist."""
+
+    def __init__(self, path: Path):
+        super().__init__(f"{path} not found: run nma-kit from the course root (the folder with myst.yml)")
+        self.path = path
+
+
+@dataclass(frozen=True)
+class Settings:
+    github_repo: str | None
+    tutorials_dir: str = DEFAULT_TUTORIALS_DIR
+    notebooks_branch: str = DEFAULT_NOTEBOOKS_BRANCH
+    nma: dict = field(default_factory=dict)
+
+
+def _yaml(text: str) -> dict:
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def read_nma_block(text: str) -> dict:
+    """The top-level `nma:` block of myst.yml ({} if absent or not a mapping)."""
+    block = _yaml(text).get("nma")
+    return block if isinstance(block, dict) else {}
+
+
+def _github_repo(data: dict) -> str | None:
+    project = data.get("project")
+    url = project.get("github") if isinstance(project, dict) else None
+    match = GITHUB_RE.search(url.strip()) if isinstance(url, str) else None
+    return match.group(1) if match else None
+
+
+def _setting(nma: dict, section: str, key: str, default: str) -> str:
+    value = (nma.get(section) or {}).get(key) if isinstance(nma.get(section), dict) else None
+    return value if isinstance(value, str) and value.strip() else default
+
+
+def load_settings(myst_text: str) -> Settings:
+    data = _yaml(myst_text)
+    nma = read_nma_block(myst_text)
+    return Settings(
+        github_repo=_github_repo(data),
+        tutorials_dir=_setting(nma, "paths", "tutorials", DEFAULT_TUTORIALS_DIR).strip("/"),
+        notebooks_branch=_setting(nma, "notebooks", "branch", DEFAULT_NOTEBOOKS_BRANCH),
+        nma=nma,
+    )
+
+
+def read_settings(path: Path = MYST_CONFIG) -> Settings:
+    path = Path(path)
+    if not path.is_file():
+        raise MissingConfig(path)
+    return load_settings(path.read_text(encoding="utf-8"))
+
+
+def page_location(settings: Settings, page: str | Path) -> tuple[str, str] | None:
+    """(rel_dir, stem) of a page path relative to the course root, or None if
+    it is outside the tutorials dir. 'tutorials/W1/T1.md' -> ('W1', 'T1')."""
+    path = PurePosixPath(Path(page).as_posix())
+    try:
+        rel = path.relative_to(settings.tutorials_dir)
+    except ValueError:
+        return None
+    rel_dir = rel.parent.as_posix()
+    return ("" if rel_dir == "." else rel_dir), rel.stem