Add public present function (#163)

.github/pull_request_template.md

@@ -0,0 +1,7 @@
+<!--- Provide a general summary of your changes here. -->
+
+Tasks
+-----
+
+- [ ] Updated changelog.
+- [ ] Updated documentation.

.github/workflows/quality-check.yml

@@ -45,7 +45,7 @@ jobs:
       - name: Make sure we can build the package
         run: poetry build -vvv
       - name: Run tests
-        run: poetry run pytest --cov --cov-report=xml
+        run: poetry run pytest --cov --cov-report=xml --durations=20
       - name: Upload coverage
         uses: codecov/[email protected]
         with:

docs/assets/style.css

@@ -0,0 +1,26 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+/* Mark external links as such. */
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="rgb(0, 0, 0)" d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  position: relative;
+  top: 0.1em;
+  margin-left: 0.2em;
+  margin-right: 0.1em;
+
+  height: 1em;
+  width: 1em;
+  border-radius: 100%;
+  background-color: var(--md-typeset-a-color);
+}
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}

CHANGELOG.md → docs/changelog.md

@@ -1,10 +1,16 @@
 # Changelog
 
+## 0.4.2
+
+### Added
+
+- [#163](https://github.com/JoshKarpel/spiel/pull/163) Added a public `present` function that presents the deck at the given file.
+
 ## 0.4.1
 
 ### Fixed
 
-- [#157](https://github.com/JoshKarpel/spiel/pull/157) Pinned to Textual v0.4.0 to work around https://github.com/Textualize/textual/issues/1274
+- [#157](https://github.com/JoshKarpel/spiel/pull/157) Pinned to Textual v0.4.0 to work around [Textual#1274](https://github.com/Textualize/textual/issues/1274).
 
 ## 0.4.0
 

docs/presenting.md

@@ -0,0 +1,36 @@
+# Presenting Decks
+
+Depending on your preferred workflow,
+you can start a presentation in a variety of different ways.
+
+## Using the `spiel` CLI
+
+!!! warning "Under Construction"
+
+## Using the `present` function
+
+The `present` function lets you start a presentation programmatically (i.e., from a Python script).
+
+::: spiel.present
+
+If your deck is defined in `talk/slides.py` like so:
+
+```python title="talk/slides.py"
+from spiel import Deck, present
+
+deck = Deck(name=f"pytest")
+
+...  # construct your deck
+
+if __name__ == "__main__":
+    present(__file__)
+```
+
+You can then present the deck by running
+```console
+$ python talk/slides.py
+```
+or
+```console
+$ python -m talk.slides
+```

mkdocs.yml

@@ -2,6 +2,9 @@ site_name: Spiel
 
 repo_url: https://github.com/JoshKarpel/spiel
 
+extra_css:
+  - assets/style.css
+
 theme:
   name: material
   favicon: assets/favicon.png
@@ -29,6 +32,16 @@ theme:
 plugins:
   - tags
   - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_root_heading: true
+            heading_level: 3
+            docstring_section_style: spacy
+            merge_init_into_class: true
+            show_if_no_docstring: true
+            show_source: false
 
 markdown_extensions:
   - admonition
@@ -60,3 +73,5 @@ extra:
 nav:
   - Introduction: index.md
   - Sandboxed Execution: sandboxed-execution.md
+  - Presenting: presenting.md
+  - changelog.md

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "spiel"
-version = "0.4.1"
+version = "0.4.2"
 description = "A framework for building and presenting richly-styled presentations in your terminal using Python."
 readme="README.md"
 homepage="https://github.com/JoshKarpel/spiel"

spiel/__init__.py

@@ -1,3 +1,4 @@
+from spiel.app import present
 from spiel.constants import __version__
 from spiel.deck import Deck
 from spiel.slide import Slide

spiel/app.py

@@ -4,13 +4,14 @@
 import code
 import datetime
 import importlib.util
+import os
 import sys
 from asyncio import wait
 from contextlib import contextmanager, redirect_stderr, redirect_stdout
 from functools import cached_property, partial
 from pathlib import Path
 from time import monotonic
-from typing import Callable, Iterator
+from typing import Callable, Iterator, Optional
 
 from rich.style import Style
 from rich.text import Text
@@ -186,3 +187,19 @@ def suspend(self) -> Iterator[None]:
     @property
     def deck_grid_width(self) -> int:
         return max(self.console.size.width // 35, 1)
+
+
+def present(deck_path: Path | str, watch_path: Optional[Path | str] = None) -> None:
+    """
+    Present the deck defined in the given `deck_path`.
+
+    Args:
+        deck_path: The file to look for a deck in.
+        watch_path: When filesystem changes are detected below this path (recursively), reload the deck from the `deck_path`.
+    """
+    os.environ["TEXTUAL"] = ",".join(sorted(["debug", "devtools"]))
+
+    deck_path = Path(deck_path).resolve()
+    watch_path = Path(watch_path or deck_path.parent).resolve()
+
+    SpielApp(deck_path=deck_path, watch_path=watch_path).run()

spiel/cli.py

@@ -1,4 +1,3 @@
-import os
 import shutil
 from pathlib import Path
 from textwrap import dedent
@@ -11,7 +10,7 @@
 from rich.text import Text
 from typer import Argument, Option, Typer
 
-from spiel.app import SpielApp
+from spiel.app import present
 from spiel.constants import DEMO_DIR, DEMO_FILE, PACKAGE_DIR, PACKAGE_NAME, __version__
 from spiel.renderables.debug import DebugTable
 
@@ -39,8 +38,8 @@
 )
 
 
-@cli.command()
-def present(
+@cli.command(name="present")
+def _present(
     path: Path = Argument(
         ...,
         dir_okay=False,
@@ -55,14 +54,7 @@ def present(
     """
     Present a deck.
     """
-    _present(deck_path=path, watch_path=watch)
-
-
-def _present(deck_path: Path, watch_path: Path) -> None:
-    os.environ["TEXTUAL"] = ",".join(sorted(["debug", "devtools"]))
-
-    app = SpielApp(deck_path=deck_path, watch_path=watch_path)
-    app.run()
+    present(deck_path=path, watch_path=watch)
 
 
 @cli.command()
@@ -154,7 +146,7 @@ def present_demo() -> None:
     """
     Present the demo deck.
     """
-    _present(deck_path=DEMO_FILE, watch_path=PACKAGE_DIR)
+    present(deck_path=DEMO_FILE, watch_path=PACKAGE_DIR)
 
 
 @demo.command()