Notebook lint (#135)

* add colab and download links to notebooks

* strip unnecessary output from cells

this removes output from cells not marked `keep_output`

* use find and awk

.github/workflows/main.yml

@@ -51,6 +51,11 @@ jobs:
         # Runs this as long as setup succeeds.
         if: ${{ !cancelled() && steps.setup.conclusion == 'success' }}
 
+      - name: Run `nbstripout-check`
+        run: uv run poe nbstripout-check
+        # Runs this as long as setup succeeds.
+        if: ${{ !cancelled() && steps.setup.conclusion == 'success' }}
+
   tests-and-type-check:
     runs-on: ubuntu-latest
     strategy:

docs/styles.css

@@ -6,4 +6,7 @@
 }
 .green {
     color: #228B22;
+}
+.colab {
+    color:  #F9AB00;
 }

mkdocs.yml

@@ -17,6 +17,7 @@ plugins:
 - search
 - blog
 - mkdocs-jupyter:
+    include_source: True
     remove_tag_config:
       remove_input_tags: ["hide_code"]
       remove_cell_tags: ["hide_cell"]

overrides/main.html

@@ -0,0 +1,20 @@
+<!-- See https://squidfunk.github.io/mkdocs-material/customization/#overriding-blocks -->
+
+{% extends "base.html" %}
+
+{% block content %}
+{% if page.nb_url %}
+    <a href="{{ page.nb_url }}" title="Download Notebook" class="md-content__button md-icon">
+        <span class="twemoji">
+            {% include ".icons/material/download.svg" %}
+        </span>
+    </a>
+    <a href="https://colab.research.google.com/github/datastax/graph-rag/blob/main/docs/{{ page.file.src_uri}}" title="Open in Colab" class="md-content__button md-icon">
+        <span class="twemoji colab">
+            {% include ".icons/simple/googlecolab.svg" %}
+        </span>
+    </a>
+{% endif %}
+
+{{ super() }}
+{% endblock content %}

pyproject.toml

@@ -52,6 +52,7 @@ dev = [
     "pytest-cov>=4.0.0",
     "pytest-asyncio>=0.25.2",
     "poethepoet>=0.32.1",
+    "nbstripout>=0.8.1",
 ]
 
 docs = [
@@ -136,6 +137,14 @@ sequence = [
     {cmd = "uvx ${DEPTRY} src tests", cwd = "packages/graph-rag-example-helpers"},
 ]
 
+[tool.poe.tasks.nbstripout]
+help = "Runs `nbstripout` to remove output"
+shell = "find . -name '*.ipynb' | awk 'system(\"git check-ignore --quiet \" $0)' | xargs nbstripout"
+
+[tool.poe.tasks.nbstripout-check]
+help = "Runs `nbstripout` to remove output"
+shell = "find . -name '*.ipynb' | awk 'system(\"git check-ignore --quiet \" $0)' | xargs nbstripout --verify"
+
 [tool.poe.tasks.lint]
 help = "Runs all formatting, lints, and checks (fixing where possible)"
 sequence = [ "lock-fix", "fmt-fix", "lint-fix", "type-check", "dep-check"]