implement: Generate the question-format tables from the export (t33)

Author: peterbjohnson

docs/source/conf.py

@@ -62,7 +62,13 @@
 graphviz_output_format = "svg"
 
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    # Tables that question-format.md includes: pages of their own otherwise.
+    "_autosummary/question-format/*.md",
+]
 source_suffix = [".rst", ".md"]
 
 copybutton_prompt_text = "$ "

docs/source/question_format.py

@@ -133,10 +133,12 @@ def _flatten(
     A key holding an object is descended into, so that `workedSolution` becomes
     `workedSolution.content`, unless it has a note of its own — `gradeParams` and
     `config` hold whatever the box type needs, and are described in prose instead.
+    An empty object is a row like any other: descending into it would yield nothing,
+    so a new key holding `{}` would go unnoticed rather than asking for a note.
     """
     for key, value in obj.items():
         full_path = f"{path}{key}"
-        if isinstance(value, dict) and full_path not in notes:
+        if isinstance(value, dict) and value and full_path not in notes:
             yield from _flatten(value, notes, f"{full_path}.")
         else:
             yield full_path, value

tests/test_question_format_docs.py

@@ -49,12 +49,15 @@ def test_tables_cover_the_exported_keys(tmp_path: Path) -> None:
     assert "response.responseInput.config" in _table_keys(tmp_path / "response_area.md")
 
 
-def test_a_key_with_no_note_is_named(tmp_path: Path) -> None:
+# An empty object holds no keys to descend into, so it has to be a row in its own
+# right for a new key to be named rather than silently dropped.
+@pytest.mark.parametrize("value", [1, {}])
+def test_a_key_with_no_note_is_named(value: object, tmp_path: Path) -> None:
     """A key added to the schema stops the build, saying which key needs a note."""
     export_dir = Path(shutil.copytree(EXPORTS[0], tmp_path / "export"))
     file = sorted(export_dir.glob("question_*.json"))[0]
     question = json.loads(file.read_text())
-    question["madeUp"] = 1
+    question["madeUp"] = value
     file.write_text(json.dumps(question))
 
     with pytest.raises(ValueError, match="madeUp"):