Merge pull request #50 from apiad/develop

v20.2.1

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Alejandro Piad, <https://apiad.net> and contributors.
+Copyright (c) 2020 Alejandro Piad, <https://apiad.net> and contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Readme.md

@@ -8,7 +8,7 @@
 [<img alt="Gitter" src="https://img.shields.io/gitter/room/apiad/auditorium">](https://gitter.im/auditorium-slides/community)
 [<img alt="Demo" src="https://img.shields.io/badge/demo-browse-blueviolet"></img>](https://auditorium-demo.apiad.net)
 
-<img src="https://apiad.net/auditorium/assets/logo.png"></img>
+<!-- <img src="https://apiad.net/auditorium/assets/logo.png"></img> -->
 
 > A Python-powered slideshow creator with steroids.
 
@@ -50,6 +50,7 @@ If you want to quickly grok `auditorium`, the best option is to [look at the dem
 * [Authoring a slideshow with Python](https://apiad.net/auditorium/quickstart/#python-first)
 * [Authoring a slideshow with Markdown](https://apiad.net/auditorium/quickstart/#markdown-first)
 * [Rendering a slideshow as purely static HTML](https://apiad.net/auditorium/quickstart/#going-full-static)
+* [Hosting a slideshow online for free](https://apiad.net/auditorium/hosting/#hosting-freely-with-auditorium-publish)
 
 ## Made with Auditorium
 

auditorium/__main__.py

@@ -5,6 +5,7 @@
 import webbrowser
 
 from auditorium import Show
+from auditorium.watcher import Watcher
 
 
 class Auditorium:
@@ -14,13 +15,17 @@ def run(
         *,
         host: str = "127.0.0.1",
         port: int = 6789,
-        debug: bool = False,
+        reload: bool = False,
         instance_name: str = "show",
     ):
         "Runs a custom Python script as a slideshow."
 
         show = Show.load(path, instance_name)
-        show.run(host=host, port=port, debug=debug)
+
+        if reload:
+           show = Watcher(path, instance_name)
+
+        show.run(host=host, port=port, debug=reload)
 
     @staticmethod
     def publish(

auditorium/watcher.py

@@ -0,0 +1,33 @@
+import os, sys, time
+import asyncio
+import fire
+
+
+class Watcher:
+    def __init__(self, files, callback=None):
+        self.files = files
+        self.callback = callback
+
+    def files_to_timestamp(self):
+        return dict ([(f, os.path.getmtime(f)) for f in self.files])
+
+    async def run(self):
+        before = self.files_to_timestamp()
+
+        while True:
+            await asyncio.sleep(1)
+            after = self.files_to_timestamp()
+
+            modified = []
+
+            for f in before.keys():
+                if os.path.getmtime(f) != before.get(f):
+                    modified.append(f)
+
+            if modified: print('Modified: {}'.format(', '.join(modified)))
+
+            before = after
+
+
+if __name__ == "__main__":
+    fire.Fire(Watcher)

docs/api/cli.md

@@ -0,0 +1,4 @@
+# The `auditorium` CLI
+
+!!! warning
+    This section is under construction. More content will be added shortly.

docs/api/context.md

@@ -0,0 +1,4 @@
+# The `Context` class
+
+!!! warning
+    This section is under construction. More content will be added shortly.

docs/api/show.md

@@ -0,0 +1,188 @@
+# The `Show` class
+
+!!! warning
+    This section is for advanced usage. Please read the [Quick Start](/quickstart/) guides first.
+
+!!! note
+    This section asumes a Python-first approach for simplicity.
+    You can use all of `auditorium` features in a Markdown-first approach
+    with [runnable code blocks](/quickstart/#markdown-first).
+
+The `Show` class is the first class you will need to interact
+with when using `auditorium`. All your slideshows begin with something like:
+
+```python
+from auditorium import Show
+
+show = auditorium.Show("My Show Title")
+```
+
+## Creating slides
+
+The most important use of your `show` instance is the `@slide` decorator, which
+allows you to create slides. A slide is created by decorating a function (or actually any callable)
+with `@show.slide` like this:
+
+```python
+@show.slide
+def first_slide(ctx):
+    # content
+```
+
+Everything that can be included **inside** a slide is discussed in the [Context](/api/context/) page.
+
+!!! note
+    Slides are sorted in the order in which they are declared in your Python script.
+
+### Customizing slides
+
+The `@slide` decorator can receive an optional parameter `id` to configure a specific slide.
+
+```python
+@show.slide(id="the-first-slide")
+def first_slide(ctx):
+    # content
+```
+
+The slide identifier is used in HTML as anchor for that slide. Hence, when running
+the slideshow, the previous slide would be located at `http://localhost:6789/#/the-first-slide`.
+If no `id` is provided the slide identifier is built from the callable `__name__` parameter,
+hence in the previous example it would be located at `http://localhost:6789/#/first_slide`
+
+!!! warning
+    Note that when using additional parameters, you have to use the form `@show.slide(...)`
+    with parenthesis, but when not using parameters, you can use the decorator directly as
+    `@show.slide` without parenthesis.
+
+Default slide ids are OK if you don't care about having those ugly underscores in your slide
+anchors in HTML. In any case, you can always author your slideshow first and then add
+pretty slide identifiers afterwards.
+
+### Vertical slides
+
+Vertical slides are an effective way to add "read-more" like content to a slideshow.
+You can see them in action at <https://auditorium-demo.apiad.net/#/vertical_slides>.
+
+Vertical slides are added *after* a main slide, using a modified form of the `@slide` decorator.
+Instead of using `@show.slide` you use `@main_slide.slide` where `main_slide` is the actual
+function (or any other callable) that corresponds to the main slide.
+
+```python
+@show.slide
+def main_slide(ctx):
+    # This will be a regular slide
+
+@main_slide.slide
+def vertical_1(ctx):
+    # This one is vertical to `main_slide`
+
+@show.slide
+def other_slide(ctx):
+    # This one is another main slide
+
+@other_slide.slide
+def vertical_2(ctx):
+    # This one is vertical to `other_slide`
+
+@other_slide.slide
+def vertical_3(ctx):
+    # This one is also vertical to `other_slide`,
+    # under the previous (`vertical_2`)
+```
+
+!!! note
+    Vertical slides can be declared at any moment *after* but not necesarily *under* the main slide.
+    This allows you to organize all your main slides at the top of a script and then add vertical slides when
+    you think is convenient.
+
+## Running the show
+
+Once all slides are in, you can run a show by calling directly the `show.run` method:
+
+```python
+show.run('localhost', 6789)
+```
+
+However, this method is actually **not recommended**. Instead it is *preferred* to use:
+
+```bash
+auditorium run /path/to/myshow.py [--host HOST] [--port PORT]
+```
+
+The second method is preferred because it is more aligned with other usages such as `auditorium publish`
+and, in the future, we will add a `--reload` option to allow hot-reload when you save your slideshow.
+
+!!! error
+    When calling `run` you can get an error like:
+
+        :::bash
+        (!) You need `uvicorn` installed in order to call `run`.
+
+    This means you didn't installed `uvicorn` when installing `auditorium`, which is necessary
+    for actually serving the HTML. You can fix it by installing like this:
+
+        pip install auditorium[server]
+
+    Serverless installations are smaller and useful if you only want to use `render` or `publish`,
+    or [deploy to a serverless cloud provider](/hosting/#hosting-as-serverless-functions-at-nowsh).
+
+## Rendering the show
+
+You can obtain a static HTML with embedded resources ready to be served with:
+
+```python
+static_html = show.render(theme="white")
+
+with open("/path/to/myshow.html", "w") as fp:
+    fp.write(static_html)
+```
+
+The reason why `render` returns a `string` rather than saving to a file is because you could
+use this functionality in a serverless cloud provider or any other context where you cannot
+interact directly with path-based files. It's up to you how to make use of the rendered HTML.
+
+That said, if you use the [CLI command](/api/cli) `render` you can achieve this more easily with:
+
+```python
+auditorium render /path/to/myshow.py > /path/to/myshow.html
+```
+
+## Loading a show
+
+The static method `Show.load` takes in a path and loads the corresponding show instance.
+
+```python
+show = Show.load("/path/to/show.py")
+```
+
+It works with both Python (`myshow.py`) and Markdown (`myshow.md`) file extensions.
+It is useful in contexts where you can serve multiple slideshows, for example,
+in a server context where you want to map URL paths to specific shows.
+
+After calling `load` you receive a `Show` instance with all it can do.
+
+## Appending multiple shows
+
+You can build a slideshow in parts, some in Python, some in Markdown, and then
+use `show.append` to connect them. It works with `Show` instances and path names as well.
+
+```python
+show = Show("Main Show")
+# ... build show
+
+# append another instance
+other_show = Show("Other show")
+# ... build other_show
+show.append(other_show)
+
+# append by path
+show.append("/path/to/anothershow.py") # Python
+show.append("/path/to/anothershow.md") # Markdown
+```
+
+This allows you to build a slideshow in parts. Maybe some slides are more
+convenient in Markdown-first mode because they are mostly static content,
+while a few specific slides are very tricky and it's better to code them in Python.
+
+!!! warning
+    This section is under construction. More content will be added shortly.

docs/hosting.md

@@ -1,7 +1,7 @@
 # Hosting your slideshow
 
 If you are presenting on a big screen connected to your own computer, all you need to do is
-`auditorium run [file]`, and you can present from [localhost:6789](http://localhost:6789) as usual.
+`auditorium run`, and you can present from [localhost:6789](http://localhost:6789) as usual.
 
 However, there are many cases where you are either not presenting from your computer, or you want
 to host your slideshow publicly for others to follow. Here are some ideas.
@@ -12,7 +12,7 @@ If the audience can ping your computer, then the easiest solution to
 simply do:
 
 ```bash
-auditorium run [file] --host=0.0.0.0
+auditorium run /path/to/file --host=0.0.0.0
 ```
 Then give them your public IP address. In Linux, run `ip addr` to see it.
 
@@ -30,14 +30,15 @@ with a server that renders the slide and proxies all incoming requests back to y
 To use it, simple run:
 
 ```bash
-auditorium publish [file] --name [your-slideshow-name]
+auditorium publish /path/to/file --name [your-slideshow-name]
 ```
 
 Then head over to `http://auditorium.apiad.net/your-slideshow-name/` and enjoy!
 
-> **NOTE:** This service is provided as-is with no guarantees whatsoever. The service runs
-> on a development server that is restarted often (at least twice a day), so slideshows are **not** guaranteed to stay
-> up for a long time. Don't use this service in mission critical presentations.
+!!! warning
+    This service is provided as-is with no guarantees whatsoever. The service runs
+    on a development server that is restarted often (at least twice a day), so slideshows are **not** guaranteed to stay
+    up for a long time. Don't use this service in mission critical presentations.
 
 If you need finer control then you can host the server yourself on your own infrastructure
 and thus ensure that it's online when you need it. Just run:
@@ -47,14 +48,29 @@ auditorium server [--host HOST] [--port PORT]
 ```
 
 Make sure the server is publicly accessible. You'll probably use some kind of web server,
-or `--host 0.0.0.0` and `--port 80` which you can totally do since `auditorium` ships
+or run it with `--host 0.0.0.0` and `--port 80`, which you can totally do since `auditorium` ships
 with `uvicorn` which is a fully fledged production web server.
 Then publish to your own address with:
 
 ```bash
-auditorium publish [file] --name [name] --server [ws://your-server:port] # or wss://
+auditorium publish /path/to/file --name [name] --server [ws://your-server:port] # or wss://
 ```
 
+!!! error
+    When calling `server` you can get an error like:
+
+        :::bash
+        (!) You need `uvicorn` installed in order to call `server`.
+
+    This means you didn't installed `uvicorn` when installing `auditorium`, which is necessary
+    for actually serving the HTML. You can fix it by installing like this:
+
+        pip install auditorium[server]
+
+    Serverless installations are smaller and useful if you only want to use `render` or `publish`,
+    or [deploy to a serverless cloud provider](/hosting/#hosting-as-serverless-functions-at-nowsh).
+
+
 ## Hosting temporarily through `ngrok`
 
 Another option is to use [`ngrok`](https://ngrok.com/).
@@ -80,7 +96,7 @@ The do have paid plans for securing a custom domain.
 If your slideshow is purely static, then you ran run:
 
 ```bash
-auditorium render [file] > index.html
+auditorium render /path/to/file > index.html
 ```
 
 Then upload the file to a Github repository.

docs/index.md

@@ -8,7 +8,7 @@
 [<img alt="Gitter" src="https://img.shields.io/gitter/room/apiad/auditorium">](https://gitter.im/auditorium-slides/community)
 [<img alt="Demo" src="https://img.shields.io/badge/demo-browse-blueviolet"></img>](https://auditorium-demo.apiad.net)
 
-<img src="https://apiad.net/auditorium/assets/logo.png"></img>
+<!-- <img src="https://apiad.net/auditorium/assets/logo.png"></img> -->
 
 > A Python-powered slideshow creator with steroids.
 
@@ -50,6 +50,7 @@ If you want to quickly grok `auditorium`, the best option is to [look at the dem
 * [Authoring a slideshow with Python](https://apiad.net/auditorium/quickstart/#python-first)
 * [Authoring a slideshow with Markdown](https://apiad.net/auditorium/quickstart/#markdown-first)
 * [Rendering a slideshow as purely static HTML](https://apiad.net/auditorium/quickstart/#going-full-static)
+* [Hosting a slideshow online for free](https://apiad.net/auditorium/hosting/#hosting-freely-with-auditorium-publish)
 
 ## Made with Auditorium
 

docs/quickstart.md

@@ -1,5 +1,8 @@
 # Quick Start
 
+This section provides quick hints for starting using `auditorium` right now. However,
+the best way to grok it is looking at the [demo](https://auditorium-demo.apiad.net).
+
 ## Python First
 
 In `auditorium` you create a presentation via the `Show` class:
@@ -148,3 +151,7 @@ auditorium render <file.[py|md]> > <output.html>
 ```
 
 This will render the slideshow in an HTML file with all CSS and JavaScript embedded. Just copy this single HTML file and open it on any browser. You won't need to have `auditorium` installed. However, do keep in mind that all of the backend code will execute only once for the initial rendering, so your animations will be frozen at the starting frame and none of the interaction will work.
+
+## Read on
+
+The [API docs](/api/show/) have a more in-depth explanation about all topics covered here.