Adding quickstart page and updating README with the same content (#174)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Josh Karpel <josh.karpel@gmail.com>

.github/workflows/quality-check.yml

@@ -21,6 +21,7 @@ jobs:
       PLATFORM: ${{ matrix.platform }}
       PYTHON_VERSION: ${{ matrix.python-version }}
       PYTHONUTF8: 1  # https://peps.python.org/pep-0540/
+      COLORTERM: truecolor
     steps:
       - name: Check out repository
         uses: actions/checkout@v3.2.0

README.md

@@ -1,7 +1,8 @@
 # Spiel
 
-[![PyPI](https://img.shields.io/pypi/v/spiel)](https://pypi.org/project/spiel/)
-[![PyPI - License](https://img.shields.io/pypi/l/spiel)](https://pypi.org/project/spiel/)
+[![PyPI](https://img.shields.io/pypi/v/spiel)](https://pypi.org/project/spiel)
+[![PyPI - License](https://img.shields.io/pypi/l/spiel)](https://pypi.org/project/spiel)
+[![Docs](https://img.shields.io/badge/docs-exist-brightgreen)](https://www.spiel.how)
 
 [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/JoshKarpel/spiel/main.svg)](https://results.pre-commit.ci/latest/github/JoshKarpel/spiel/main)
 [![codecov](https://codecov.io/gh/JoshKarpel/spiel/branch/main/graph/badge.svg?token=2sjP4V0AfY)](https://codecov.io/gh/JoshKarpel/spiel)
@@ -24,6 +25,37 @@ $ spiel demo present
 ![The first slide of the demo deck](https://raw.githubusercontent.com/JoshKarpel/spiel/main/docs/assets/demo.svg)
 ![The demo deck in "deck view"](https://raw.githubusercontent.com/JoshKarpel/spiel/main/docs/assets/deck.svg)
 
+## Quick Start
+
+If you want to jump right in,
+install Spiel (`pip install spiel`),
+create a file called `deck.py`,
+and copy this code into it:
+```python
+from rich.console import RenderableType
+
+from spiel import Deck, present
+
+deck = Deck(name="Your Deck Name")
+
+
+@deck.slide(title="Slide 1 Title")
+def slide_1() -> RenderableType:
+    return "Your content here!"
+
+
+if __name__ == "__main__":
+    present(__file__)
+```
+
+That is the most basic Spiel presentation you can make.
+To present the deck, run `python deck.py`.
+You should see:
+
+![Barebones slide](https://raw.githubusercontent.com/JoshKarpel/spiel/main/docs/assets/quickstart_basic.svg)
+
+Check out the [Quick Start tutorial](https://www.spiel.how/quickstart) to continue!
+
 ## Documentation
 
 To learn more about Spiel, take a look at the [documentation](https://www.spiel.how).

docs/examples/quickstart.py

@@ -0,0 +1,14 @@
+from rich.console import RenderableType
+
+from spiel import Deck, present
+
+deck = Deck(name="Your Deck Name")
+
+
+@deck.slide(title="Slide 1 Title")
+def slide_1() -> RenderableType:
+    return "Your content here!"
+
+
+if __name__ == "__main__":
+    present(__file__)

docs/generate_screenshots.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
 
+import os
 from collections.abc import Iterable
 from datetime import datetime
 from functools import partial
@@ -15,7 +16,9 @@
 
 ROOT_DIR = Path(__file__).resolve().parent.parent
 ASSETS_DIR = ROOT_DIR / "docs" / "assets"
-DECK_FILE = ROOT_DIR / "spiel" / "demo" / "demo.py"
+
+# lie to Rich to make sure the screenshots are always generated in full color
+os.environ["TERMCOLOR"] = "truecolor"
 
 
 def take_reproducible_screenshot(app: App[object]) -> str:
@@ -46,10 +49,10 @@ async def auto_pilot(pilot: Pilot, name: str, keys: Iterable[str]) -> None:
     await pilot.app.action_quit()
 
 
-def take_screenshot(name: str, size: tuple[int, int], keys: Iterable[str]) -> None:
+def take_screenshot(name: str, deck_file: Path, size: tuple[int, int], keys: Iterable[str]) -> None:
     SpielApp(
-        deck_path=DECK_FILE,
-        watch_path=DECK_FILE.parent,
+        deck_path=deck_file,
+        watch_path=deck_file.parent,
         show_messages=False,
         fixed_time=datetime(year=2022, month=12, day=17, hour=15, minute=31, second=42),
     ).run(
@@ -59,6 +62,11 @@ def take_screenshot(name: str, size: tuple[int, int], keys: Iterable[str]) -> No
     )
 
 
-take_screenshot(name="demo", size=(130, 35), keys=())
-take_screenshot(name="deck", size=(130, 35), keys=("d", "right", "down"))
-take_screenshot(name="help", size=(110, 35), keys=("?",))
+demo_deck = ROOT_DIR / "spiel" / "demo" / "demo.py"
+quickstart_deck = ROOT_DIR / "docs" / "examples" / "quickstart.py"
+
+take_screenshot(name="demo", deck_file=demo_deck, size=(130, 35), keys=())
+take_screenshot(name="deck", deck_file=demo_deck, size=(130, 35), keys=("d", "right", "down"))
+take_screenshot(name="help", deck_file=demo_deck, size=(110, 35), keys=("?",))
+take_screenshot(name="quickstart_basic", deck_file=quickstart_deck, size=(60, 20), keys=())
+take_screenshot(name="quickstart_code", deck_file=demo_deck, size=(140, 45), keys=("right",))

docs/quickstart.md

@@ -0,0 +1,133 @@
+# Quick Start
+
+## The Most Basic Deck
+
+After installing Spiel (`pip install spiel`),
+create a file called `deck.py` and copy this code into it:
+
+```python
+from rich.console import RenderableType
+
+from spiel import Deck, present
+
+deck = Deck(name="Your Deck Name")
+
+
+@deck.slide(title="Slide 1 Title")
+def slide_1() -> RenderableType:
+    return "Your content here!"
+
+
+if __name__ == "__main__":
+    present(__file__)
+```
+
+That is the most basic Spiel presentation you can make.
+To present the deck, run `python deck.py`.
+You should see:
+
+![Barebones slide](./assets/quickstart_basic.svg)
+
+In the example above, you first create a `Deck` and provide the name of your presentation.
+Then you create slides by decorating functions with `@deck.slide()`, providing the title of the slide.
+The slide function can return anything that
+[Rich can render](https://rich.readthedocs.io/en/stable/console.html#printing);
+that return value will be displayed as the slide's content when you present it.
+The order of the `@deck.slide()`-decorated functions in your file is the order in which they will appear in your presentation.
+
+Running `python deck.py` started the presentation because of the call to `present()` in the
+[`if __name__ == "__main__"` block](https://stackoverflow.com/questions/419163/what-does-if-name-main-do).
+
+To see available keybindings for doing things like moving between slides,
+press `?` to open the help view, which should look like this:
+
+![Help view](./assets/help.svg)
+
+## Making Richer Slides
+
+You can make your slides a lot prettier, of course.
+As mentioned above, Spiel renders its slides using Rich, so you can bring in Rich functionality to spruce up your slides.
+Let's explore some advanced features by recreating one of the slides from the demo deck.
+Update your `deck.py` file with these imports and utility definitions:
+
+``` python
+import inspect
+from textwrap import dedent
+
+from rich.box import SQUARE
+from rich.console import RenderableType
+from rich.layout import Layout
+from rich.markdown import Markdown
+from rich.padding import Padding
+from rich.panel import Panel
+from rich.style import Style
+from rich.syntax import Syntax
+
+from spiel import Deck, Slide, present
+from spiel.deck import Deck
+
+
+SPIEL = "[Spiel](https://github.com/JoshKarpel/spiel)"
+RICH = "[Rich](https://rich.readthedocs.io/)"
+
+def pad_markdown(markup: str) -> RenderableType:
+    return Padding(Markdown(dedent(markup), justify="center"), pad=(0, 5))
+```
+
+And then paste this code in to your `deck.py` file below your first slide:
+
+```python
+@deck.slide(title="Decks and Slides")
+def code() -> RenderableType:
+    markup = f"""\
+        ## Decks are made of Slides
+
+        Here's the code for `Deck` and `Slide`!
+
+        The source code is pulled directly from the definitions via [inspect.getsource](https://docs.python.org/3/library/inspect.html#inspect.getsource).
+
+        ({RICH} supports syntax highlighting, so {SPIEL} does too!)
+        """
+    root = Layout()
+    upper = Layout(pad_markdown(markup), size=len(markup.split("\n")) + 1)
+    lower = Layout()
+    root.split_column(upper, lower)
+
+    def make_code_panel(obj: type) -> RenderableType:
+        lines, line_number = inspect.getsourcelines(obj)
+        return Panel(
+            Syntax(
+                "".join(lines),
+                lexer="python",
+                line_numbers=True,
+                start_line=line_number,
+            ),
+            box=SQUARE,
+            border_style=Style(dim=True),
+            height=len(lines) + 2,
+        )
+
+    lower.split_row(
+        Layout(make_code_panel(Deck)),
+        Layout(make_code_panel(Slide)),
+    )
+
+    return root
+```
+
+We start out by creating our text content and setting up some `Layout`s, which will let us divide the slide space into chunks.
+Then, we create the `make_code_panel` function to take some lines of code from the `Deck` and `Slide` classes
+and put them in a syntax-highlighted `Panel` (with some additional fancy Rich styling).
+Finally, we add the code panels to our layout side-by-side and return `root`, the top-level `Layout`, from the function.
+
+Run `python deck.py` again and go to the second slide (press `?` if you're not sure how to navigate!):
+
+![Demo Code Slide](./assets/quickstart_code.svg)
+
+Check out the source code of the [demo deck](https://github.com/JoshKarpel/spiel/blob/main/spiel/demo/demo.py)
+for more inspiration on ways to use Rich to make your slides beautiful!
+Spiel provides a `spiel` CLI tool to make this easy:
+
+- Present the demo deck in your terminal by running `spiel demo present`.
+- View the source in your terminal with `spiel demo source`.
+- Copy it to use as a starting point with `spiel demo copy <destination>`.

mkdocs.yml

@@ -70,6 +70,7 @@ extra:
 
 nav:
   - Introduction: index.md
+  - quickstart.md
   - presenting.md
   - gallery.md
   - contributing.md