Syncing changes from main (#174)

d0c-s4vage · Nov 3, 2022 · 0658cb8 · 0658cb8
1 parent 7a46aab
commit 0658cb8
Show file tree

Hide file tree

Showing 20 changed files with 1,111 additions and 69 deletions.
diff --git a/.github/workflows/pypi_publish.yml b/.github/workflows/pypi_publish.yml
@@ -14,17 +14,16 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: "3.10"
-      - name: Set VERSION number
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+      - name: Fill placeholders
         run: |
           version_num="${{github.ref_name}}"
           # strip the leading v
           version_num=${version_num#v}
-          echo "Replacing {{VERSION}} with '$version_num'"
-          echo "Files with {{VERSION}}:"
-          grep -rl '{{VERSION}}' .
-          grep -rl '{{VERSION}}' . | xargs sed -i "s/{{VERSION}}/$version_num/g"
-          echo "Files with {{VERSION}} after replacing:"
-          grep -rl '{{VERSION}}' . || true
+          bin/fill_placeholders "$version_num"
       - name: Install pypa/build
         run: python -m pip install build --user
       - name: Build binary wheel + tarball

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,6 @@
 # Changelog
 
+- [v2.5.0](#v250)
 - [v2.4.1](#v241)
 - [v2.4.0](#v240)
 - [v2.3.2](#v232)
@@ -21,6 +22,15 @@
 - [v0.2.0](#v020)
 - [v0.1.0](#v010)
 
+## v2.5.0
+
+Adds the `--tutorial` CLI option.
+
+|    type | PR/ticket                                                | author                                       | description                               |
+|--------:|----------------------------------------------------------|----------------------------------------------|-------------------------------------------|
+| feature | [#169](https://github.com/d0c-s4vage/lookatme/issue/169) | [@d0c-s4vage](https://github.com/d0c-s4vage) | Adds the `--tutorial` CLI option          |
+|     bug | [#168](https://github.com/d0c-s4vage/lookatme/issue/168) | [@d0c-s4vage](https://github.com/d0c-s4vage) | Adds documentation for progressive slides |
+
 ## v2.4.1
 
 Bug fix - theme and style override precedence issues. The CLI params `--theme`

diff --git a/README.md b/README.md
@@ -24,14 +24,21 @@ tool.
 ## Features
 
 * Markdown rendering
+* Built-in tutorial slides `lookatme --tutorial`
 * Live (input file modification time watching) and manual reloading
 * Live terminals embedded directly in slides
 * Syntax highlighting using [Pygments](https://pygments.org/)
 * Loading external files into code blocks
 * Support for contrib extensions
 * Smart slide splitting
+* Progressive slides with `<!-- stop -->` comments between block elements
 
-### Tour
+### Tutorial
+
+```bash
+pip install --upgrade lookatme
+lookatme --tutorial
+```
 
 General tour
 
@@ -68,25 +75,24 @@ Usage: lookatme [OPTIONS] [INPUT_FILES]...
 Options:
   --debug
   -l, --log PATH
+  --tutorial TEXT                 As a flag: show all tutorials. With a
+                                  value/comma-separated values: show the
+                                  specific tutorials. Use the value 'help' for
+                                  more help
   -t, --theme [dark|light]
-  --style [default|emacs|friendly|colorful|autumn|murphy|manni|monokai|perldoc|pastie|borland|trac|native|fruity|bw|vim|vs|tango|rrt|xcode|igor|paraiso-light|paraiso-dark|lovelace|algol|algol_nu|arduino|rainbow_dash|abap|solarized-dark|solarized-light|sas|stata|stata-light|stata-dark|inkpot]
+  --style [default|emacs|friendly|friendly_grayscale|colorful|autumn|murphy|manni|material|monokai|perldoc|pastie|borland|trac|native|fruity|bw|vim|vs|tango|rrt|xcode|igor|paraiso-light|paraiso-dark|lovelace|algol|algol_nu|arduino|rainbow_dash|abap|solarized-dark|solarized-light|sas|staroffice|stata|stata-light|stata-dark|inkpot|zenburn|gruvbox-dark|gruvbox-light|dracula|one-dark|lilypond|nord|nord-darker|github-dark]
   --dump-styles                   Dump the resolved styles that will be used
                                   with the presentation to stdout
-
   --live, --live-reload           Watch the input filename for modifications
                                   and automatically reload
-
   -s, --safe                      Do not load any new extensions specified in
                                   the source markdown. Extensions specified
                                   via env var or -e are still loaded
-
   --no-ext-warn                   Load new extensions specified in the source
                                   markdown without warning
-
   -i, --ignore-ext-failure        Ignore load failures of extensions
   -e, --exts TEXT                 A comma-separated list of extension names to
                                   automatically load (LOOKATME_EXTS)
-
   --single, --one                 Render the source as a single slide
   --version                       Show the version and exit.
   --help                          Show this message and exit.

diff --git a/bin/fill_placeholders b/bin/fill_placeholders
@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )"
+THIS_PROG="$0"
+SUBPROGRAM="ls"
+
+. "$DIR"/_utils.sh
+
+
+function show_help {
+    cat <<-EOF
+USAGE: $THIS_PROG VERSION_NUMBER
+
+This script will fill all placeholder values in the lookatme me project.
+Specifically:
+
+* {{VERSION}} will be replaced with the version number (no 'v' prefix!)
+* {{LOOKATME_HELP_OUTPUT}} will be replaced with output from  "lookatme --help"
+* {{LOOKATME_HELP_OUTPUT_INDENTED}} will be replaced with the indented
+  output of "lookatme --help"
+EOF
+}
+
+function replace_in_files {
+    local placeholder="$1"
+    local replacement="$2"
+
+    log "==== Replacing $placeholder"
+    (
+        cd "$DIR"/..
+        files_to_replace=$(grep -rl "$placeholder" $(git ls-files) | grep -v bin/fill_placeholders)
+        python3 <(cat <<-EOF
+import sys
+
+placeholder = sys.argv[1]
+replacement = sys.argv[2]
+files_to_replace = sys.argv[3:]
+
+for file in files_to_replace:
+    with open(file, "r") as f:
+        data = f.read()
+
+    new_data = data.replace(placeholder, replacement)
+    if new_data != data:
+        print("    replacing {}".format(file))
+    with open(file, "w") as f:
+        f.write(new_data)
+EOF
+        ) "$placeholder" "$replacement" $files_to_replace
+    )
+}
+
+function set_version {
+    replace_in_files "{{VERSION}}" "$VERSION"
+}
+
+function set_help_output {
+    local help_output=$(cd "$DIR"/.. ; python3 -m lookatme --help)
+    replace_in_files "{{LOOKATME_HELP_OUTPUT}}" "$help_output"
+
+    local help_output_indented=$(sed 's/^/    /' <<<$help_output)
+    replace_in_files "{{LOOKATME_HELP_OUTPUT_INDENTED}}" "$help_output_indented"
+}
+
+
+function parse_args {
+    VERSION=""
+    while [ $# -ne 0 ] ; do
+        param="$1"
+        shift
+
+        case "$param" in
+            --help|-h)
+                show_help
+                exit 1
+                ;;
+            *)
+                VERSION="$param"
+                ;;
+        esac
+    done
+}
+
+parse_args "$@"
+# needs to come first, can contain {{VERSION}} placeholders
+set_help_output
+set_version
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -20,37 +20,7 @@ The ``lookatme`` CLI has a few options to control it's behavior:
 
 .. code-block:: text
 
-    Usage: lookatme [OPTIONS] [INPUT_FILES]...
-
-      lookatme - An interactive, terminal-based markdown presentation tool.
-
-      See https://lookatme.readthedocs.io/en/v{{VERSION}} for documentation
-
-    Options:
-      --debug
-      -l, --log PATH
-      -t, --theme [dark|light]
-      --style [default|emacs|friendly|colorful|autumn|murphy|manni|monokai|perldoc|pastie|borland|trac|native|fruity|bw|vim|vs|tango|rrt|xcode|igor|paraiso-light|paraiso-dark|lovelace|algol|algol_nu|arduino|rainbow_dash|abap|solarized-dark|solarized-light|sas|stata|stata-light|stata-dark|inkpot]
-      --dump-styles                   Dump the resolved styles that will be used
-                                      with the presentation to stdout
-
-      --live, --live-reload           Watch the input filename for modifications
-                                      and automatically reload
-
-      -s, --safe                      Do not load any new extensions specified in
-                                      the source markdown. Extensions specified
-                                      via env var or -e are still loaded
-
-      --no-ext-warn                   Load new extensions specified in the source
-                                      markdown without warning
-
-      -i, --ignore-ext-failure        Ignore load failures of extensions
-      -e, --exts TEXT                 A comma-separated list of extension names to
-                                      automatically load (LOOKATME_EXTS)
-
-      --single, --one                 Render the source as a single slide
-      --version                       Show the version and exit.
-      --help                          Show this message and exit.
+{{LOOKATME_HELP_OUTPUT_INDENTED}}
 
 ``--live`` / ``--live-reload``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -67,6 +67,25 @@ A basic, optional YAML header may be included at the top of the slides:
 
     Some text
 
+Slides can be progressively rendered by adding ``<!-- stop -->`` comments
+between block elements (paragraphs, tables, lists, etc.):
+
+.. code-block:: md
+
+   # Progressive Slide
+
+   <!-- stop -->
+
+   Paragraph 1
+
+   <!-- stop -->
+
+   Paragraph 2
+
+   <!-- stop -->
+
+   Paragraph 3
+
 .. toctree::
   :maxdepth: 2
 

diff --git a/examples/tour.md b/examples/tour.md
@@ -97,6 +97,30 @@ A quote is below:
 
 ---
 
+# Progressive Slides
+
+Add a `<!-- stop -->` comment between paragraphs to progressively render
+the current slide!
+
+For example, the markdown in the codeblock below is used at the end of this
+slide:
+
+```markdown
+paragraph 1
+
+<!-- stop -->
+
+paragraph 2
+```
+
+paragraph 1
+
+<!-- stop -->
+
+paragraph 2
+
+---
+
 # Extensions
 
 lookatme supports extensions that can add additional functionality to lookatme

diff --git a/lookatme/__main__.py b/lookatme/__main__.py
@@ -16,19 +16,32 @@
 import lookatme.config
 import lookatme.log
 import lookatme.tui
+import lookatme.tutorial
 from lookatme.pres import Presentation
 from lookatme.schemas import StyleSchema
 
 
 @click.command("lookatme")
-@click.option("--debug", "debug", is_flag="True", default=False)
+@click.option("--debug", "debug", is_flag=True, default=False)
 @click.option(
     "-l",
     "--log",
     "log_path",
     type=click.Path(writable=True),
     default=os.path.join(tempfile.gettempdir(), "lookatme.log"),
 )
+@click.option(
+    "--tutorial",
+    "tutorial",
+    is_flag=False,
+    flag_value="all",
+    show_default=True,
+    help=(
+        "As a flag: show all tutorials. "
+        "With a value/comma-separated values: show the specific tutorials. "
+        "Use the value 'help' for more help"
+    )
+)
 @click.option(
     "-t",
     "--theme",
@@ -101,6 +114,7 @@
     nargs=-1,
 )
 def main(
+    tutorial,
     debug,
     log_path,
     theme,
@@ -126,6 +140,25 @@ def main(
     if len(input_files) == 0:
         input_files = [io.StringIO("")]
 
+    if tutorial:
+        if tutorial == "all":
+            tutors = ["general", "markdown"]
+        else:
+            tutors = [x.strip() for x in tutorial.split(",")]
+
+        theme_mod = __import__("lookatme.themes." + theme, fromlist=[theme])
+        lookatme.config.set_global_style_with_precedence(
+            theme_mod,
+            {},
+            code_style,
+        )
+        tutorial_md = lookatme.tutorial.get_tutorial_md(tutors)
+        if tutorial_md is None:
+            lookatme.tutorial.print_tutorial_help()
+            return 1
+
+        input_files = [io.StringIO(tutorial_md)]
+
     preload_exts = [x.strip() for x in extensions.split(",")]
     preload_exts = list(filter(lambda x: x != "", preload_exts))
     pres = Presentation(