docs: Fill the documentation with introduction, examples, installatio…

…n and getting started instructions

Signed-off-by: Sietze van Buuren <s.van.buuren@gmail.com>

docs/examples.md

@@ -1,3 +1,36 @@
 # Examples
 
-## :construction: Under construction :construction: 
+Examples of workings recipe can be found in
+[simple-cdd-yam-recipes](https://github.com/swvanbuuren/simple-cdd-yaml-recipes).
+
+## Example recipe `base` 
+
+The simplest recipe that
+[simple-cdd-yam-recipes](https://github.com/swvanbuuren/simple-cdd-yaml-recipes)
+features is the recipe
+[`base`](https://github.com/swvanbuuren/simple-cdd-yaml-recipes/blob/master/recipes/base.yaml),
+which is shown below.
+
+The recipe consists of:
+
+- A series of variables with default values, which can be overridded when
+  including this recipe in another recipe. Variables are used throughout the recipe using the `jinja2` notation `{{variable}}`.
+- Profile name definition.
+- A series of actions:
+    - `recipe` action. Include another recipe, where some variables are being
+      overridden.
+    - `conf` action: Set simple-CDD variables and environment variables.
+    - `preseed` action: The Debian-CD configuration is controlled via preseed.
+      files. Here, a template is used in which variables are substituted.
+    - `apt` action: Install Debian packages.
+    - `run` action (`script`): Runs a script. Note that variables in the script
+      also might get substituted.
+    - `run` action (`command`): Runs a command.
+    - `overlay` action: Deploys the contents of a give directory onto the
+      system. This can be done by `root` (default) or by a given user.
+- Also note that it's possible to include more complex behavior using `jinja2`,
+  such as if statement as shown in this examples.
+
+```yaml title="base.yaml"
+--8<-- "https://raw.githubusercontent.com/swvanbuuren/simple-cdd-yaml-recipes/master/recipes/base.yaml"
+```

docs/getting_started.md

@@ -1,3 +1,51 @@
 # Getting started
 
-## :construction: Under construction :construction: 
+This page will code through to process of installing, generating a Simple-CDDp
+rofile from a YAML recipe.
+
+## Installation
+
+First install Simple-CDD-YAML according to the [installation
+instructions](installation.md).
+
+## Building a Simple-CDD profile
+
+In order to build a profile from a given recipe file `<recipe-name>.yaml`,
+located in the subdirectory `recipe`, issue the following:
+
+```bash
+simple-cdd-yaml --recipe recipe/<recipe-name>.yaml
+``` 
+
+Make sure the  corresponding environment in which `simple-cdd-yaml` is installed
+has been activated prior to issues this command. Alternatively, you can prepend
+the command with a command to activate the environment (here called
+`<simple-cdd-yaml-venv>`):
+
+```bash
+( . ~/.venv/<simple-cdd-yaml-venv>/bin/activate && \
+    simple-cdd-yaml --recipe recipe/<recipe-name>.yaml )
+```
+
+Note that the commands are wrapped in parentheses `( ... )` to assure that the
+command runs in an isolated shell.
+
+## Results
+
+After a successful build, a `profiles` directory should become visible that
+contains the Simple-CDD outputs, all named after profile name `<profile>`, but with different extensions. These include:
+
+- `<profile>.preseed`
+- `<profile>.packages`
+- `<profile>.postinst`
+- `<profile>.conf`
+- `<profile>.extra`
+
+The last file `<profile>.extra` contains references to additional files that are
+included into the profile. These are located in the directory `extra`. Finally,
+also a `debos` directory might appear, if you enabled the `debos` output option
+during profile build.
+
+Visit the [Simple-CDD repository](https://salsa.debian.org/debian/simple-cdd) or
+[Howto](https://wiki.debian.org/Simple-CDD/Howto) to learn more about the
+contents of profile files and how to build an images from them using [Simple-CDD](https://wiki.debian.org/Simple-CDD).

docs/index.md

@@ -3,9 +3,12 @@
 Welcome to the documentation of
 [Simple-CDD-YAML](https://github.com/swvanbuuren/simple-cdd-yaml)!
 
-## :construction: Under construction :construction: 
+Have a look at the [introduction](introduction.md) to get a quick idea of what Simple-CDD-YAML
+is and what it can do.
 
-At the time of writing, only the [Code Reference](reference/index.md) is filled
-with life.
+To get going follow the instructions in [getting started](getting_started.md).
 
-The [getting started](getting_started.md) and [examples](examples.md) sections are still under construction.
+The [examples](examples.md) page features a simple example of a `YAML` recipe.
+
+Refer to the [code reference](reference/index.md) for the actual code and
+implementation details.

docs/installation.md

@@ -0,0 +1,26 @@
+# Installation
+
+It is recommended to install Simple-CDD-YAML into a dedicated environment (e.g.
+[virtaulenv](https://github.com/pypa/virtualenv)). After the environment has been activated, it can simply installed using `pip`:
+
+```bash
+pip install simple-cdd-yaml
+``` 
+
+Alternatively, Simple-CDD-YAML can be installed from source:
+
+```bash
+git clone https://github.com/swvanbuuren/simple-cdd-yaml.git
+cd simple-cdd-yaml
+pip install .
+```
+
+## Usage
+
+Now that Simple-CDD-YAML is installed, the command `simple-cdd-yaml` should be
+available in your virtual python environment. You can test it out, by querying
+the help:
+
+```bash
+simple-cdd-yaml --help
+```

docs/introduction.md

@@ -0,0 +1,41 @@
+# Introduction
+
+Simple-CDD-YAML uses YAML recipes to generate the profile files required by
+Simple-CDD. A recipe consists of actions, that generate or append files in the
+Simple-CDD profile.
+
+## Actions
+
+Simple-CDD-YAML features the following actions (for an
+exemplary profile called `<profile>`):
+
+- `recipe` action: embed another recipe
+- `conf` action: compose a `<profile>.conf` file by supplying (environment)
+  variables
+- `preseed` action: define a preseed file
+- `apt` action: add packages
+- `run` action: add a command or script (to `<profile>.postinst`)
+- `overlay` action: add an overlay (an overlay is a file structure that is
+  compressed into one single file and automatically added to the file
+  `<profile>.extra`. A corresponding command to decompress the overlay is added
+  to `<profile>.postinst`)
+- `extra` action: add extra file
+- `downloads` action: add extra packages
+- `debos` action: [only in debos mode] add pre- and post-action to debos recipe
+  output
+
+Some of the actions support substitutions using
+[jinja](https://palletsprojects.com/p/jinja/) notation, making it easier to
+reuse scripts, preseeds and recipes. By defining variables with default values
+at the top of a recipe it becomes easy to reuse and nest recipes.
+
+A few actions also support different roles: by default scripts are executed and
+overlays are deployed as root, but you can also specify to have this done by a
+given user.
+
+## Next steps
+
+Refer to [getting started](getting_started.md) to install Simple-CDD-YAML,
+create a profile from a YAML recipe and build an image using Simple-CDD.
+
+Vist [code reference](reference/index.md) to learn more about the implementation and underlying code of Simple-CDD-YAML.

mkdocs.yml

@@ -9,21 +9,37 @@ theme:
   - navigation.sections
   - navigation.tabs
   - navigation.indexes
+  - content.code.copy
 
 plugins:
   - search
-  - mkdocstrings
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_root_toc_entry: false
 
 markdown_extensions:
   - attr_list
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets:
+      url_download: true
+  - pymdownx.superfences
 
 nav:
-  - Welcome: index.md
-  - Getting Started: getting_started.md
-  - Examples: examples.md
+  - Welcome:
+    - index.md
+    - Introduction: introduction.md
+    - Getting started: getting_started.md
+    - Installation: installation.md
+    - Examples: examples.md
   - Code Reference:
     - reference/index.md
     - Simple-CDD-YAML: reference/simple_cdd_yaml.md