Port slide creation user guide

docs/userguide/basics.md

@@ -0,0 +1,89 @@
+# Basics
+A presentation (set of slides) is represented in *Elsie* with the [`Slides`](elsie.slides.Slides)
+class. The most important parameters of the presentation is the width and height of the resulting
+PDF pages, which also affects the resulting aspect ratio. The default size if `1024x768`, which
+corresponds to aspect ratio `4:3`.
+
+Here is an example of creating a new presentation:
+```python
+import elsie
+slides = elsie.Slides(width=1024, height=768)
+```
+Once you have a `Slides` object, you can create new slides from it.
+
+## Creating slides
+You can create new slides in two ways, either using the [`new_slide`](elsie.slides.Slides.new_slide)
+method or via a [decorator](#decorator). The `new_slide` method will create a new slide, but for
+convenience, it will not return the slide itself, but its [root box](layout.md), so that you can
+use the returned object immediately for adding things to the slide. Except for some advanced usage,
+you shouldn't ever need to deal with the [`Slide`](elsie.slidecls.Slide) instance itself.
+
+```python
+slide = slides.new_slide(bg_color="blue")
+```
+
+Once you have a slide, you can add content to it, for example [text](text.md), [images](images.md),
+[shapes](shapes.md) or [source code](syntax_highlighting.md).
+
+### Decorator
+A more convenient way of creating a slide is using the [`slide`](elsie.slides.Slides.slide)
+decorator. If you apply it to a function, it will create a new slide and pass its root box as a
+parameter to the function. It will also set the name of the slide according to the name of the
+decorated function.
+
+```python
+@slides.slide()
+def slide1(slide: elsie.Box):
+    slide.box().text("Hello")
+```
+
+Both `slide` and `new_slide` have parameters that allow you to change the background color and SVG
+viewbox of the slide. You can also choose its name (see [below](#name-policy))
+or enable [debug draw mode](layout.md#debug-draw-mode).
+
+## Rendering slides
+After you have created all of your desired slides and filled them with content, you can render your
+presentation using the [`render`](elsie.slides.Slides.render) method. There are several useful
+parameters of this method:
+
+- `output`: Change the output filename of the rendered PDF (default is `slides.pdf`).
+- `slide_postprocessing`: Apply some postprocessing function to all slides. See an example
+[here](../cookbook/postprocessing.md).
+- `select_slides`: Render only a selected subset of slides.
+- `return_units`: Return a list of SVG slides without rendering them. This can be useful if you
+just want to build your slides using *Elsie*, but render them in a another way.
+
+*Elsie* uses caching to speed-up the rendering. The cache will be created in a directory named
+`elsie-cache`.
+
+## Name policy
+If you create slides in an interactive Python session (for example in `IPython` or
+[Jupyter](jupyter.md)), you might inadvertedly create new slides after modifying and re-executing
+a piece of code.
+
+For example, if this code was inside a Jupyter notebook cell:
+```
+@slides.slide()
+def slide1(slide):
+    slide.box().text("Hello")
+```
+Each time you would execute the cell, a new slide would be added to the presentation, which is
+probably not what you want.
+
+To solve this issue, *Elsie* contains a so-called *name policy*, which decides how to react to the
+situation where the same slide is created repeatedly. Slides are identified by their name, which you
+either pass to `new_slide` or it is determined automatically if the [decorator](#decorator) is used.
+
+The `Slides` instance has one of the following name policies, which decides what to do when a new
+slide is created:
+
+- `unique`: Creating two slides with the same name will result in an error. This is to stop you from
+creating multiple instances of the same slide inadvertedly. Note that when a name of a slide is
+unset (it is `None`), the slide will be allowed to be created.
+- `replace`: When a slide with the same name already exists, the previous slide will be replaced by
+the new slide.
+- `ignore`: The name of slides will not be checked, essentially turns off name policy.
+- `auto` (the default): Uses `replace` when running inside Jupyter, otherwise uses `unique`.
+
+Since Jupyter automatically sets a name policy which is most probably the one that you want in an
+interactive environment (`replace`), you will not have to deal with name policy most of the time.

docs/userguide/layout.md

@@ -21,15 +21,18 @@ as the return value of the [`new_slide`](elsie.slides.Slides.new_slide) method o
 Here we create three boxes as children of the top-level slide box and create a child text item
 in each box.
 ```elsie,width=200,height=200,skip=2
-@slides.slide()
-def three_boxes(slide):
-    slide.box().text("Box 1")
-    slide.box().text("Box 2")
-    slide.box().text("Box 3")
+slide.box().text("Box 1")
+slide.box().text("Box 2")
+slide.box().text("Box 3")
 ```
 
+Note: for brevity, most code snippets in this user guide assume that there is a `slides` variable
+containing a `Slides` object and a `slide` variable containing a `Slide` object. The `render`
+method call is also omitted from most of the examples that display rendered slide output.
+
+### Debug draw mode
 The boxes themselves are invisible, but they have caused the three text items to be rendered
-below one another. If you are fine-tuning or debugging the layout of your slide and you want to see
+below one another. If you are fine-tuning or debugging the layout of your slide, and you want to see
 the extents and bounds of your boxes, you can use the
 [`debug_boxes`](elsie.slides.Slides.slide) parameter when creating a slide:
 ```elsie,width=200,height=200,debug,skip=2

mkdocs.yml

@@ -15,6 +15,7 @@ nav:
   - getting_started.md
   - gallery.md
   - User guide:
+    - userguide/basics.md
     - userguide/layout.md
     - userguide/revealing.md
     - userguide/text.md