Docs updated

docs/guide/basics.md

@@ -1,6 +1,7 @@
 
 # Basics
 
+
 ## Slide deck
 
 A presentation (a set of slides) is represented in Nelsie as an instance of SlideDeck class.
@@ -44,3 +45,12 @@ def first_slide(slide):
 The decorator immediately calls the wrapped function that sets the content of the slide. The main function of the decorator is to break slides into individual functions for code clarity.
 
 
+## Rendering the slide deck
+
+Once all the slides have been created, you can render them into PDF with a `.render()` call on the slide deck.
+
+```python
+deck.render("slides.pdf")
+```
+
+You can also get SVG or PNG images from the slides, see the [Output formats section](output.md) for more information.

docs/guide/layout.md

@@ -0,0 +1,69 @@
+# Layout
+
+Nelsie uses a layout system that is based on the Flexbox system and adds some extra features.
+
+The central element of the Nelsie layout system is the _Box_.
+Each Nelsie slide contains a layout hierarchy tree of boxes. Boxes do not directly produce visual output, but they dictate how their children are laid out on a slide.
+
+
+# Creating a box
+
+A new box is created by calling the `.box()` method on an existing box or a slide. This will return a new box that will be a child of the element on which you call the box method. 
+
+This is a s minimal example where we create a box inside a slide:
+
+```python
+@deck.slide()
+def first_box(slide):
+    slide.box()
+```
+
+When we render this slide, we see an empty slide because the box itself produces no visual output.
+
+To make them visible, in the next example we set a background color for the boxes. We also set them to a fixed size,
+because by default box tries to be as small as possible and a box with no content takes up zero space.
+
+Example where we create three boxes:
+
+```nelsie
+@deck.slide()
+def three_boxes(slide):
+    slide.box(width=600, height=200, bg_color="red")
+    slide.box(width=600, height=200, bg_color="green")
+    slide.box(width=600, height=200, bg_color="blue")
+```
+
+# Debugging layout
+
+Another way how to visualize boxes is to set `debug_layout` to `True` in the slide configuration: 
+
+```nelsie
+@deck.slide(debug_layout=True)
+def debug_boxes(slide):
+    slide.box(width=600, height=200)
+    slide.box(width=600, height=200)
+    slide.box(width=600, height=200)
+```
+
+For more configuration for debugging layout, see [Debugging layout](../reference/debug_layout.md).
+
+
+# Box main axis
+
+Boxes can have either be vertical or horizontal main axis:
+
+* Vertical boxes place its child items vertically in a column. Their main axis is vertical and their cross axis is horizontal.
+
+* Horizontal boxes place its child items horizontally in a row. Their main axis is horizontal and their cross axis is vertical.
+
+By default, box is vertical. It can be changed by setting the parameter `row`:
+
+```nelsie
+@deck.slide()
+def three_boxes(slide):
+
+    my_box = slide.box(row=True)
+    my_box.box(width=200, height=200, bg_color="red")
+    my_box.box(width=200, height=200, bg_color="green")
+    my_box.box(width=200, height=200, bg_color="blue")
+```

docs/install.md

@@ -1,12 +1,16 @@
 # Installation
 
+
+## Installation via `pip` (recommended)
+
 ```commandline
 $ pip install nelsie
 ```
 
 Nelsie supports Linux, Windows, and MacOS X on all major platforms.
 
-# Installation from sources
+
+## Installation from sources
 
 * Install Rust (https://rustup.rs/)
 * Install [Maturin](https://www.maturin.rs/) (`pip install maturin`)

docs/mkdocs-nelsie-plugin/mkdocs_nelsie_plugin/__init__.py

@@ -14,7 +14,7 @@
 
 Example:
 ```nelsie,width=300,height=300
-slide.box().text("Hello world")
+slide.text("Hello world")
 ```
 """
 
@@ -97,22 +97,10 @@ def render_slide(
     code = "\n".join(trim_indent(code))
     template = f"""
 from nelsie import SlideDeck
-# import elsie
-# from elsie.boxtree.box import Box
-# from elsie.render.jupyter import render_slide_html as elsie_render_slide
-
-# {ctx.get_lib_code()}
-
-# slides = elsie.SlideDeck(width={width}, height={height}, name_policy="ignore")
-# slide = slides.new_slide()
-
+deck = SlideDeck()
 {code}
-
-# result = elsie_render_slide(slides._slides[-1], format="{render_format}")
 """.strip()
 
-    print(template)
-
     locals = {}
     code_object = compile(template, "nelsie_render.py", "exec")
 
@@ -148,7 +136,7 @@ def render_slide(
         """.strip()
     else:
         return f"""
-        <div><img style="border: 1px solid black" width="300" src={data_array[0]}/></div>
+        <div style="padding-bottom: 1.5em"><img style="border: 1px solid black" width="300" src={data_array[0]}/></div>
         """.strip()
 
 

docs/reference/debug_layout.md

@@ -0,0 +1,70 @@
+# Debugging layout
+
+This page describes how you an debug a layout boxes by visualizing them.
+
+
+## Enabling `debug_layout` for whole slide
+
+To visualize layout boxes you can set `debug_layout` to `True` in the slide configuration: 
+
+```nelsie
+@deck.slide(debug_layout=True)
+def example_slide(slide):
+    slide.box(width=600, height=200)
+    slide.box(width=600, height=200)
+    slide.box(width=600, height=200)
+```
+
+If the default color for displaying debug frames of boxes conflicts with the colors of your slide's content or background, you can define your own color for drawing.
+
+
+```nelsie
+@deck.slide(debug_layout="green")
+def example_slide(slide):
+    slide.box(width=600, height=200)
+    slide.box(width=600, height=200)
+    slide.box(width=600, height=200)
+```
+
+## Enabling `debug_layout` for a box
+
+You can also change the color only for a specific box by setting the `debug_layout` parameter of the box.
+You can also disable the highlighting of a specific box frame by setting `debug_layout` to `False`.
+
+```nelsie
+@deck.slide(debug_layout=True)
+def example_slide(slide):
+    slide.box(width=600, height=200)
+
+    # Set green frame for this box
+    slide.box(width=600, height=200, debug_layout="green")
+
+    # Disable layout debugging for this box
+    slide.box(width=600, height=200, debug_layout=False)
+```
+
+Or you can just enable the debug frames only for a specific box:
+
+```nelsie
+@deck.slide()
+def example_slide(slide):
+    slide.box(width=600, height=200)
+
+     # Show the debug frame for this box
+    slide.box(width=600, height=200, debug_layout="green")
+    
+    slide.box(width=600, height=200)
+```
+
+
+# Box naming
+
+You can name a box by setting the `name` parameter. The name has no effect on a layout, but it is displayed when debug frames are enabled. It may help you to find the box when there are too many boxes.
+
+Note: The slide previews in the documentation are too small to see the name. If you render the example in PDF, you will see it.
+
+```nelsie
+@deck.slide(debug_layout=True)
+def box_with_names(slide):
+    slide.box(width=600, height=200, name=">>> My-box <<<")
+```

docs/reference/output.md

@@ -0,0 +1,53 @@
+# Output formats
+
+This section shows you how to get slides in PDF, SVG or PNG and how to render slides into files or
+how to get them as Python objects.
+
+## Rendering into PDF
+
+By default, the `.render()` method on a slide deck takes a filename and creates a PDF file. 
+
+```python
+from nelsie import SlideDeck
+
+deck = SlideDeck()
+
+# Add slides here
+
+deck.render("slides.pdf")
+```
+
+
+## Rendering into SVG or PNG
+
+By setting the second parameter to "svg" or "png", you can change the output format to SVG or PNG.
+
+```python
+from nelsie import SlideDeck
+
+deck = SlideDeck()
+
+# Add slides here
+
+deck.render("output/path1", "svg") # Render slides to SVG 
+
+deck.render("output/path2", "png") # Render slides to PNG
+```
+
+Unlike PDF, the first parameter is not a path to a file, but to a directory where 
+Nelsie creates SVG (or PNG) images, one image per slide page. 
+Nelsie will create the target directory if it does not exist.
+Images are named in the format "X-Y.svg" (or "X-Y.png"), where X is the slide index and Y is a step. 
+
+
+## In-memory rendering
+
+If the first parameter of the `.render()` method is `None` then Nelsie does not create files but returns
+the images as Python objects. It returns a list of triplets (`slide_id`, `step`, `data`) where `data` are
+`bytes` instance with the image.
+
+```python
+pages = deck.render(None, "png") 
+
+print(pages)  # Print returned triplets with pages
+```

mkdocs.yml

@@ -15,7 +15,12 @@ nav:
   - api.md
   - User guide:
       - guide/basics.md
+      - guide/layout.md
       - guide/steps.md
+  - Reference manual:
+      - reference/output.md
+      - reference/debug_layout.md
+
 theme:
   name: material
   # custom_dir: docs/template