slides-xp 0.0.1__tar.gz

slides_xp-0.0.1/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.3
+Name: slides-xp
+Version: 0.0.1
+Summary: 
+Author: Maddy Guthridge
+Author-email: hello@maddyguthridge.com
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: click (>=8.1.8,<9.0.0)
+Requires-Dist: flask (>=3.1.0,<4.0.0)
+Requires-Dist: mistune (>=3.1.1,<4.0.0)
+Requires-Dist: pygments (>=2.19.1,<3.0.0)
+Requires-Dist: pyhtml-enhanced (>=2.2.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Slides XP
+
+A simple but flexible markdown slide-show viewer.
+
+## Running
+
+```sh
+sxp <directories to serve>
+```
+
+## Theming
+
+You can use the `--theme` option to specify the a built-in theme, or a path to
+a directory containing CSS theme files.
+
+The built-in themes are:
+
+* `default`
+* `xp`
+
+### Custom CSS
+
+A theme directory should contain (at least) these files:
+
+* `main.css`: main stylesheet. Always loaded.
+* `slide.css`: stylesheet for slide pages.
+* `picker.css`: stylesheet for slide picker page.
+
+These stylesheets are mounted at the `/theme` endpoint.
+
+Within these stylesheets, the following classes can be selected.
+
+* `.highlight`: code blocks
+* `.slide-content`: slide content
+* `.picker-box`: slide picker
+* `.picker-item`: slide within slide picker
+
+And the following variables are available:
+
+* `--hl-comment`: code block highlighting, comment
+* `--hl-doc`: code block highlighting, documentation
+* `--hl-keyword`: code block highlighting, keyword
+* `--hl-var`: code block highlighting, variable
+* `--hl-func`: code block highlighting, function
+* `--hl-type`: code block highlighting, type
+* `--hl-string`: code block highlighting, string
+

slides_xp-0.0.1/README.md

@@ -0,0 +1,46 @@
+# Slides XP
+
+A simple but flexible markdown slide-show viewer.
+
+## Running
+
+```sh
+sxp <directories to serve>
+```
+
+## Theming
+
+You can use the `--theme` option to specify the a built-in theme, or a path to
+a directory containing CSS theme files.
+
+The built-in themes are:
+
+* `default`
+* `xp`
+
+### Custom CSS
+
+A theme directory should contain (at least) these files:
+
+* `main.css`: main stylesheet. Always loaded.
+* `slide.css`: stylesheet for slide pages.
+* `picker.css`: stylesheet for slide picker page.
+
+These stylesheets are mounted at the `/theme` endpoint.
+
+Within these stylesheets, the following classes can be selected.
+
+* `.highlight`: code blocks
+* `.slide-content`: slide content
+* `.picker-box`: slide picker
+* `.picker-item`: slide within slide picker
+
+And the following variables are available:
+
+* `--hl-comment`: code block highlighting, comment
+* `--hl-doc`: code block highlighting, documentation
+* `--hl-keyword`: code block highlighting, keyword
+* `--hl-var`: code block highlighting, variable
+* `--hl-func`: code block highlighting, function
+* `--hl-type`: code block highlighting, type
+* `--hl-string`: code block highlighting, string

slides_xp-0.0.1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "slides-xp"
+version = "0.0.1"
+description = ""
+authors = [{ name = "Maddy Guthridge", email = "hello@maddyguthridge.com" }]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "flask (>=3.1.0,<4.0.0)",
+    "pyhtml-enhanced (>=2.2.0,<3.0.0)",
+    "click (>=8.1.8,<9.0.0)",
+    "mistune (>=3.1.1,<4.0.0)",
+    "pygments (>=2.19.1,<3.0.0)",
+]
+
+[project.scripts]
+sxp = "slides_xp.__main__:cli"
+
+[tool.poetry]
+include = ["py.typed", "css/*", "javascript/*", "themes/*"]
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.9.6"
+mypy = "^1.15.0"
+pytest = "^8.3.4"
+types-pygments = "^2.19.0.20250107"
+
+[tool.ruff]
+line-length = 79
+
+[tool.mypy]
+check_untyped_defs = true
+files = ["slides_xp", "tests"]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

slides_xp-0.0.1/slides_xp/__init__.py

@@ -0,0 +1,4 @@
+from .server import make_app
+
+
+__all__ = ["make_app"]

slides_xp-0.0.1/slides_xp/__main__.py

@@ -0,0 +1,5 @@
+from slides_xp.cli import cli
+
+
+if __name__ == '__main__':
+    cli()

slides_xp-0.0.1/slides_xp/cli.py

@@ -0,0 +1,70 @@
+"""
+CLI
+
+Main entrypoint to the program.
+"""
+
+import click
+from pathlib import Path
+from slides_xp import make_app
+
+
+HELP_TEXT = """
+sxp
+
+Slides XP CLI
+"""
+
+
+@click.command("sxp", help=HELP_TEXT, options_metavar="<options>")
+@click.argument(
+    "paths",
+    type=click.Path(
+        exists=True,
+        dir_okay=True,
+        file_okay=False,
+        readable=True,
+        path_type=Path,
+    ),
+    nargs=-1,
+    required=True,
+)
+@click.option(
+    "--theme",
+    envvar="SXP_THEME",
+    help="Theme directory to serve CSS stylesheets from",
+)
+@click.option(
+    "-h",
+    "--host",
+    default="localhost",
+    envvar="HOST",
+    help="Port to run server on",
+)
+@click.option(
+    "-p",
+    "--port",
+    type=int,
+    default=3000,
+    envvar="PORT",
+    help="Port to run server on",
+)
+@click.option(
+    "--debug",
+    is_flag=True,
+    help="Whether to enable Flask debug mode",
+)
+def cli(
+    paths: tuple[Path, ...],
+    *,
+    theme: str | None,
+    host: str,
+    port: int,
+    debug: bool,
+):
+    """
+    Entrypoint to CLI.
+    """
+    app = make_app(list(paths), theme)
+
+    app.run(host, port, debug)

slides_xp-0.0.1/slides_xp/css/root.css

@@ -0,0 +1,48 @@
+.highlight {
+
+    /* Comment */
+    & .c1,
+    & .cm {
+        color: var(--hl-comment, black);
+    }
+
+    /* Documentation */
+    & .sd {
+        color: var(--hl-doc, black);
+    }
+
+    /* Keyword */
+    & .k,
+    & .kd {
+        color: var(--hl-keyword, black);
+    }
+
+    /* Variable */
+    & .n {
+        color: var(--hl-var, black);
+    }
+
+    /* Function name */
+    & .nf {
+        color: var(--hl-func, black);
+    }
+
+    /* Class name */
+    & .nb,
+    & .kt {
+        color: var(--hl-type, black);
+    }
+
+    /* String */
+    & .s2,
+    & .sb {
+        color: var(--hl-string, black);
+    }
+
+}
+
+/* Prevent images from exceeding the bounds of the slide */
+.slide-content img {
+    max-width: 100%;
+    max-height: 50vh;
+}

slides_xp-0.0.1/slides_xp/javascript/navigator.js

@@ -0,0 +1,36 @@
+/**
+ * Navigator.js
+ *
+ * Navigate between slides
+ */
+
+
+window.addEventListener("keydown", e => {
+  const root = `${window.location.protocol}//${window.location.host}/`;
+
+  let target = null;
+  switch (e.key) {
+    case "0":
+      if (window.sxp.prev) {
+        target = `${root}${window.sxp.first}`;
+      }
+      break;
+    case "ArrowLeft":
+      if (window.sxp.prev) {
+        target = `${root}${window.sxp.prev}`;
+      }
+      break;
+    case "ArrowRight":
+      if (window.sxp.next) {
+        target = `${root}${window.sxp.next}`;
+      }
+      break;
+    case "Escape":
+      target = root;
+      break;
+  }
+  if (target !== null) {
+    window.location.href = target;
+    e.preventDefault();
+  }
+});

slides_xp-0.0.1/slides_xp/markdown.py

@@ -0,0 +1,34 @@
+"""
+Render markdown as HTML
+"""
+
+from typing import cast
+import mistune
+from pygments import highlight
+from pygments.lexers import get_lexer_by_name
+from pygments.formatters import html
+
+
+# https://mistune.lepture.com/en/latest/guide.html#customize-renderer
+class HighlightRenderer(mistune.HTMLRenderer):
+    """
+    Markdown render that adds code block highlights
+    """
+
+    def block_code(self, code, info=None):
+        if info:
+            lexer = get_lexer_by_name(info, stripall=True)
+            formatter = html.HtmlFormatter()
+            return highlight(code, lexer, formatter)
+        return "<pre><code>" + mistune.escape(code) + "</code></pre>"
+
+
+markdown = mistune.create_markdown(renderer=HighlightRenderer())
+
+
+def render_markdown(text: str) -> str:
+    """
+    Render markdown as HTML.
+    """
+    # We know it's a string, since we haven't set the renderer to None
+    return cast(str, markdown(text))

slides_xp-0.0.1/slides_xp/picker.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+import pyhtml as p
+
+
+@dataclass
+class Choice:
+    name: str
+    url: str
+
+
+def picker(root: str, choices: list[Choice], parent: str | None = None):
+    choices_html = [
+        p.div(class_="picker-item")(
+            p.a(href=f"{choice.url}")(choice.name),
+        )
+        for choice in choices
+    ]
+
+    if parent is not None:
+        choices_html.insert(
+            0, p.div(class_="picker-item")(p.a(href=parent)(".."))
+        )
+
+    return p.html(
+        p.head(
+            p.title("Slides XP"),
+            p.script(src="/javascript/navigator.js", defer=True),
+            p.link(href="/css/root.css", rel="stylesheet"),
+            p.link(href="/theme/main.css", rel="stylesheet"),
+            p.link(href="/theme/picker.css", rel="stylesheet"),
+        ),
+        p.body(
+            p.h1(root),
+            p.div(class_="picker-box")(choices_html),
+        ),
+    )

slides_xp-0.0.1/slides_xp/server.py

@@ -0,0 +1,124 @@
+from flask import Flask, Blueprint, redirect, send_file, send_from_directory
+from pathlib import Path
+import pyhtml as p
+
+from slides_xp.picker import Choice, picker
+from slides_xp.slide import slide
+from slides_xp.util import dir_contains_md, list_subdirs, slides_list
+
+
+lib_dir = Path(__file__).parent
+
+
+def error(code: int, message: str):
+    return str(
+        p.html(
+            p.body(
+                p.h1(f"Error {code}"),
+                p.p(message),
+            )
+        )
+    ), code
+
+
+def make_blueprint(name: str, root_dir: Path):
+    bp = Blueprint(name, __name__, url_prefix=f"/{name}")
+
+    @bp.get("/", defaults={"path": ""})
+    @bp.get("/<path:path>")
+    def endpoint(path: str):
+        file_path = root_dir / path
+        url = f"/{name}/{path}".removesuffix("/")
+        # Root path must be a parent of `full_path` to prevent escaping the
+        # specified directories
+        if root_dir not in [file_path, *file_path.parents]:
+            return error(403, "Illegal path")
+        # 404 if file/dir does not exist
+        if not file_path.exists():
+            return error(404, "File not found")
+        # If file, send it
+        if file_path.is_file():
+            # Render markdown files as HTML
+            if file_path.suffix == ".md":
+                return str(slide(file_path))
+            else:
+                return send_file(file_path.absolute())
+        elif dir_contains_md(file_path):
+            # Dir with markdown, render a list of slides
+            return str(
+                picker(
+                    str(root_dir),
+                    [
+                        Choice(p.name, f"{url}/{p.name}")
+                        for p in slides_list(file_path)
+                    ],
+                    parent=str(file_path.parent),
+                )
+            )
+        else:
+            # Otherwise, dir with no markdown, so render a list of subdirs
+            return str(
+                picker(
+                    str(root_dir),
+                    [
+                        Choice(p.name, f"{url}/{p.name}")
+                        for p in list_subdirs(file_path)
+                    ],
+                    parent=str(file_path.parent),
+                )
+            )
+
+    return bp
+
+
+def make_app(paths: list[Path], theme: str | None = None):
+    if theme is None:
+        theme_dir = lib_dir / "themes" / "default"
+    elif Path(theme).is_dir():
+        theme_dir = Path(theme)
+    elif (lib_dir / "themes" / theme).is_dir():
+        theme_dir = lib_dir / "themes" / theme
+    else:
+        # Invalid theme
+        theme_dir = lib_dir / "themes" / "default"
+
+    app = Flask(__name__)
+
+    for path in paths:
+        app.register_blueprint(make_blueprint(path.name, path))
+
+    @app.get("/")
+    def root():
+        """
+        Root path.
+
+        If using one path, redirect to it. Otherwise give a choice.
+        """
+        if len(paths) == 1:
+            return redirect(f"/{paths[0].name}/")
+        else:
+            return str(
+                picker(
+                    "Slides XP",
+                    [Choice(p.name, f"/{p.name}") for p in paths],
+                )
+            )
+
+    @app.get("/javascript/<path>")
+    def scripts(path):
+        return send_from_directory(lib_dir / "javascript", path)
+
+    @app.get("/css/<path>")
+    def css(path):
+        return send_from_directory(lib_dir / "css", path)
+
+    @app.get("/theme/<path>")
+    def theme_css(path):
+        return send_from_directory(theme_dir, path)
+
+    return app
+
+
+if __name__ == "__main__":
+    app = make_app([Path("temp")])
+    app.run(port=3000)

slides_xp-0.0.1/slides_xp/slide.py

@@ -0,0 +1,37 @@
+import pyhtml as p
+from pathlib import Path
+
+from slides_xp.markdown import render_markdown
+from slides_xp.util import slides_list
+
+
+def slide(file: Path) -> p.html:
+    slides = list(slides_list(file.parent))
+
+    curr_index = slides.index(file)
+
+    first = f"'{slides[0]}'" if len(slides) else "null"
+    prev = f"'{slides[curr_index - 1]}'" if curr_index > 0 else "null"
+    next = f"'{slides[curr_index + 1]}'" if curr_index < len(slides) - 1 else "null"
+
+    return p.html(
+        p.head(
+            p.title("Slides XP"),
+            p.script(src="/javascript/navigator.js", defer=True),
+            p.link(href="/css/root.css", rel="stylesheet"),
+            p.link(href="/theme/main.css", rel="stylesheet"),
+            p.link(href="/theme/slide.css", rel="stylesheet"),
+        ),
+        p.body(
+            p.script(f"""
+                window.sxp = {{
+                    first: {first},
+                    prev: {prev},
+                    next: {next},
+                }};
+            """),
+            p.div(class_="slide-content")(
+                p.DangerousRawHtml(render_markdown(file.read_text())),
+            ),
+        ),
+    )

slides_xp-0.0.1/slides_xp/themes/default/main.css

@@ -0,0 +1,20 @@
+body {
+    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+    font-size: 2rem;
+}
+
+h1 {
+    font-size: 5rem;
+    text-align: center;
+}
+
+@media (prefers-color-scheme: dark) {
+    html {
+        background-color: rgb(27, 27, 27);
+        color: white;
+    }
+}

slides_xp-0.0.1/slides_xp/themes/default/picker.css

@@ -0,0 +1,22 @@
+.picker-box {
+    min-width: 70%;
+}
+
+.picker-item a {
+    text-decoration: none;
+}
+.picker-item a:hover {
+    text-decoration: underline;
+}
+
+@media (prefers-color-scheme: light) {
+    .picker-item a {
+        color: black;
+    }
+}
+
+@media (prefers-color-scheme: dark) {
+    .picker-item a {
+        color: white;
+    }
+}

slides_xp-0.0.1/slides_xp/themes/default/slide.css

@@ -0,0 +1,43 @@
+.slide-content {
+    min-width: 70%;
+}
+
+.highlight {
+    font-family: monospace;
+    font-weight: bold;
+    border: 2px solid rgb(138, 138, 138);
+    border-radius: 10px;
+    padding: 20px;
+}
+
+.highlight>pre {
+    margin: 0px;
+}
+
+@media (prefers-color-scheme: light) {
+
+    /* Syntax highlighting, derived from VS Code "Quiet Light" theme */
+    :root {
+        --hl-comment: rgb(116, 116, 116);
+        --hl-doc: rgb(87, 151, 61);
+        --hl-keyword: rgb(122, 62, 157);
+        --hl-var: rgb(122, 62, 157);
+        --hl-func: rgb(170, 55, 49);
+        --hl-type: rgb(122, 62, 157);
+        --hl-string: rgb(87, 151, 61);
+    }
+}
+
+@media (prefers-color-scheme: dark) {
+
+    /* Syntax highlighting, derived from VS Code "Synthwave '84" theme */
+    :root {
+        --hl-comment: rgb(128, 135, 184);
+        --hl-doc: rgb(128, 135, 184);
+        --hl-keyword: rgb(254, 222, 93);
+        --hl-var: rgb(237, 119, 205);
+        --hl-func: rgb(3, 237, 249);
+        --hl-type: rgb(214, 62, 75);
+        --hl-string: rgb(255, 139, 57);
+    }
+}

slides_xp-0.0.1/slides_xp/themes/xp/main.css

@@ -0,0 +1,19 @@
+html {
+    background-image: url('/theme/bliss.jpg');
+    background-size: cover;
+    min-height: 100vh;
+}
+
+body {
+    font-family: Tahoma, Verdana, Segoe, sans-serif;
+    font-size: 2rem;
+}
+
+h1 {
+    font-size: 5rem;
+    text-align: center;
+}
+
+.highlight {
+    font-family: Consolas, Hack, monospace;
+}

slides_xp-0.0.1/slides_xp/themes/xp/slide.css

@@ -0,0 +1,31 @@
+.slide-content {
+    background:
+        /* Corners */
+        url('/theme/window-top-left.png') top left no-repeat,
+        url('/theme/window-top-right.png') top right no-repeat,
+        url('/theme/window-bottom-left.png') bottom left no-repeat,
+        url('/theme/window-bottom-right.png') bottom right no-repeat,
+        /* Edges */
+        url('/theme/window-top.png') top repeat-x,
+        url('/theme/window-bottom.png') bottom repeat-x,
+        url('/theme/window-left.png') left repeat-y,
+        url('/theme/window-right.png') right repeat-y,
+        /* Center */
+        url('/theme/window-center.png') center repeat;
+
+    clip-path: inset(7px 9px 7px 7px round 3px);
+
+    padding: 30px;
+
+    margin: 100px;
+}
+
+:root {
+    --hl-comment: rgb(125, 131, 136);
+    --hl-doc: rgb(125, 131, 136);
+    --hl-keyword: rgb(223, 58, 72);
+    --hl-var: rgb(35, 35, 35);
+    --hl-func: rgb(129, 98, 199);
+    --hl-type: rgb(129, 98, 199);
+    --hl-string: rgb(19, 42, 108);
+}

slides_xp-0.0.1/slides_xp/util.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+from typing import Generator
+
+
+def list_subdirs(path: Path) -> list[Path]:
+    return [subdir for subdir in path.iterdir() if subdir.is_dir()]
+
+
+def dir_contains_md(path: Path) -> bool:
+    """
+    Returns whether the given directory contains Markdown files.
+    """
+    return next(slides_list(path), None) is not None
+
+
+def first_slide(path: Path) -> Path:
+    """
+    Returns the path of the first slide in the given dir
+    """
+    return next(slides_list(path))
+
+
+def slides_list(path: Path) -> Generator[Path]:
+    """
+    Returns a slides list for the given directory.
+    """
+    return (
+        child for child in path.iterdir() if child.is_file() and child.suffix == ".md"
+    )