the notebook: a table of cell forms

.github/workflows/test.yml

@@ -5,7 +5,7 @@ jobs:
     strategy:
       matrix:
         python-version:
-        - 3.9
+        - "3.10"
     runs-on: ubuntu-latest
     steps:
     - name: fetch all history and tags

dodo.py

@@ -1,10 +1,9 @@
-from curses.ascii import US
 from shutil import copytree, move, copyfile
 from doit import create_after, task_params
 from pathlib import Path
 from functools import partial
 import warnings
-
+from sys import executable
 HERE = Path(__file__).parent
 
 DOCS = Path("docs")
@@ -17,6 +16,11 @@
 AUDITS = EXPORTS / "audits"
 REPORTS = EXPORTS / "reports"
 
+def do(cmd, *args):
+    from doit.cmd_base import CmdAction
+    from shlex import split
+    return CmdAction(split(cmd) + list(args), shell=False)
+
 def cp(x , y):
     x, y = map(Path, (x, y))
     if x.is_dir():
@@ -209,7 +213,7 @@ def readme(target):
             yield dict(
                 name=str(name),
                 actions=[
-                    f"jupyter nbconvert --config {c} --output {name} --output-dir {target} {nb}"
+                    do(f"{executable} -m jupyter nbconvert --config {c} --output {name} --output-dir {target} {nb}")
                 ],
                 file_dep=[nb, c],
                 targets=[t],

mkdocs.yml

@@ -56,7 +56,7 @@ nav:
     - exports/reports/notebooks.md
     - exports/reports/configs.md
   - nbconvert_html5 module:
-    - DEVELOPER.md
+    - nbconvert_html5.md
 
 hooks:
   - hooks.py

nbconvert_html5/__init__.py

@@ -1 +1,15 @@
-from .exporters import Html5
+"""nbconvert_soup organically added tooling to the nbconvert library.
+
+nbconvert is a community convention for converting ipynb files to 
+other formats like html, pdf, epub, tex. the goal of this work is to
+test accessibility remediations made to the html version of notebooks.
+nbconvert suits our needs, and  it is well integrated into the jupyter command line for reuse.
+
+we found that nbconvert's configuration system was valuable for recording 
+the state of manual testing sessions.
+
+we called this library `nbconvert_html5` because we hope discover html5 patterns
+that offer a POUR notebook reading experience for assistive tech.
+"""
+
+from .form_exporter import FormExporter as Html5

nbconvert_html5/audit.py

@@ -58,7 +58,7 @@ async def test_axe_one(file: Path, browser=None, **config):
             config.setdefault("runOnly", ["best-practice", "wcag22aa", "wcag2aaa"])
             config.setdefault("allowedOrigins", ["<same_origin>"])
             logger.info(f"inject axe {page.url}")
-            await page.evaluate(requests.get("https://unpkg.com/axe-core").text)
+            await page.evaluate(requests.get("https://cdn.jsdelivr.net/npm/axe-core").text)
             logger.info(f"running axe tests {page.url}")
             try:
                 return await page.evaluate(f"window.axe.run(window.document, {dumps(config)})")

nbconvert_html5/exporters.py

@@ -1,3 +1,5 @@
+"""nbconvert exporters towards accessible notebook html"""
+
 import os
 import os.path
 from pathlib import Path
@@ -13,7 +15,8 @@
 PROMPT_RE = compile("(In|Out)(\s|&nbsp;){0,1}\[(?P<n>[0-9]+)\]")
 
 
-def soupify(body):
+def soupify(body: str) -> BeautifulSoup:
+    """convert a string of html to an beautiful soup object"""
     return BeautifulSoup(body, features="html.parser")
 
 
@@ -29,31 +32,23 @@ class PostProcessExporter(HTMLExporter):
     def post_process_code_cell(self, cell):
         pass
     A/B testing with out requiring `nbconvert` or notebook knowleldge."""
-
-    export_from_notebook = "html5"
+    enabled = True
     extra_template_paths = List([(DIR / "templates").absolute().__str__()])
     post_processor = Callable(lambda x: x).tag(config=True)
 
-    def code_set_cell_label(self, cell, label=None):
-        pass
-
-    def post_process_cell(self, cell):
-        pass
-
-    def post_process_markdown_cell(self, cell):
-        pass
-
-    def post_process_code_cell(self, cell):
-        pass
-
-    # def _template_file_default(self):
-    #     return "html5-lab.j2"
-
 
 from traitlets import Bool, CUnicode
 
 
-class Html5(PostProcessExporter):
+class Html5Test(PostProcessExporter):
+    """the primary exporter produced by notebooks for all
+
+    this class has a lot of flags that we designed to test.
+    the naming occurred organically as the project progressed.
+    we try to limit the degrees of freedom of each trait
+    so that the configuration changes are minimal.
+    """
+
     def from_notebook_node(self, nb, **kw):
         result, meta = super().from_notebook_node(nb, **kw)
         result = self.post_process_html(result)
@@ -114,6 +109,9 @@ def from_notebook_node(self, nb, **kw):
     scroll_to_top = Bool(False, help="include a scroll to top link").tag(config=True)
 
     def post_process_head(self, soup):
+        """post process the head of the document.
+
+        add custom css based on flags"""
         script = soup.new_tag("style", type="text/css", rel="stylesheet")
         script.string = ""
         if self.increase_prompt_visibility:
@@ -292,3 +290,4 @@ def write_config(cls, dir=Path.cwd(), file="jupyter_nbconvert_config.py"):
 
         print(f"writing config to {target}")
         target.write_text(cls.generate_config())
+