Introduce LinkedFile resource as start to showing code samples.

Author: pauleveritt

src/psc/gallery/examples/interest_calculator/index.md

@@ -2,5 +2,8 @@
 title: Compound Interest Calculator
 subtitle: Enter some numbers, get some numbers.
 author: meg-1
+linked_files: 
+  - calculator.py
+  - styles.css
 ---
 The *body* description.

src/psc/resources.py

@@ -17,13 +17,12 @@
 from psc.here import HERE
 from psc.here import PYODIDE
 
-
 EXCLUSIONS = ("pyscript.css", "pyscript.js", "favicon.png")
 
 
 def tag_filter(
-    tag: Tag,
-    exclusions: tuple[str, ...] = EXCLUSIONS,
+        tag: Tag,
+        exclusions: tuple[str, ...] = EXCLUSIONS,
 ) -> bool:
     """Filter nodes from example that should not get included."""
     attr = "href" if tag.name == "link" else "src"
@@ -81,6 +80,27 @@ class Resource:
     extra_head: str = ""
 
 
+linked_file_mapping = dict(
+    py="python",
+    css="css",
+    html="html"
+)
+
+
+@dataclass
+class LinkedFile:
+    """A source file on disk that gets attached to an example."""
+
+    path: Path
+    language: str = field(init=False)
+    body: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        """Read the file contents into the body."""
+        self.language = linked_file_mapping[self.path.suffix[1:]]
+        self.body = self.path.read_text()
+
+
 @dataclass
 class Example(Resource):
     """Create an example from an HTML location on disk.
@@ -91,9 +111,10 @@ class Example(Resource):
     Meaning, HERE / "examples" / name / "index.html".
     """
 
-    subtitle: str = ""
-    description: str = ""
-    author: str | None = None
+    subtitle: str = field(init=False)
+    description: str = field(init=False)
+    author: str = field(init=False)
+    linked_files: list[LinkedFile] = field(default_factory=list)
 
     def __post_init__(self) -> None:
         """Extract most of the data from the HTML file."""
@@ -107,13 +128,22 @@ def __post_init__(self) -> None:
         self.description = str(md.render(md_fm.content))
 
         # Main, extra head example's HTML file.
-        index_html_file = HERE / "gallery/examples" / self.name / "index.html"
+        this_example_path = HERE / "gallery/examples" / self.name
+        index_html_file = this_example_path / "index.html"
         if not index_html_file.exists():  # pragma: nocover
             raise ValueError(f"No example at {self.name}")
-        soup = BeautifulSoup(index_html_file.read_text(), "html5lib")
+        index_html_text = index_html_file.read_text()
+        soup = BeautifulSoup(index_html_text, "html5lib")
         self.extra_head = get_head_nodes(soup)
         self.body = get_body_content(soup)
 
+        # Process any linked files
+        linked_paths = [*["index.html"], *md_fm.get("linked_files", [])]
+        for linked_name in linked_paths:
+            linked_path = this_example_path / linked_name
+            linked_file = LinkedFile(path=linked_path)
+            self.linked_files.append(linked_file)
+
 
 @dataclass
 class Author(Resource):

tests/test_resources.py

@@ -5,7 +5,7 @@
 from bs4 import BeautifulSoup
 
 from psc.here import HERE
-from psc.resources import Example
+from psc.resources import Example, LinkedFile
 from psc.resources import Page
 from psc.resources import Resources
 from psc.resources import get_body_content
@@ -15,7 +15,6 @@
 from psc.resources import is_local
 from psc.resources import tag_filter
 
-
 IS_LOCAL = is_local()
 
 
@@ -122,14 +121,24 @@ def test_example_bad_path() -> None:
 
 def test_example() -> None:
     """Construct an ``Example`` and ensure it has all the template bits."""
-    this_example = Example(name="hello_world")
-    assert this_example.title == "Hello World"
+    this_example = Example(name="interest_calculator")
+    assert this_example.title == "Compound Interest Calculator"
     assert (
-        this_example.subtitle
-        == "The classic hello world, but in Python -- in a browser!"
+            this_example.subtitle
+            == "Enter some numbers, get some numbers."
     )
-    assert "hello_world.css" in this_example.extra_head
-    assert "<h1>Hello ...</h1>" in this_example.body
+    assert "styles.css" in this_example.extra_head
+    assert "Welcome to the" in this_example.body
+
+    linked_files = this_example.linked_files
+    assert "html" == linked_files[0].language
+
+
+def test_linked_file() -> None:
+    """Correctly create a LinkedFile."""
+    linked_path = HERE / "gallery/examples/altair/index.html"
+    linked_file = LinkedFile(path=linked_path)
+    assert "html" == linked_file.language
 
 
 def test_markdown_page() -> None: