add docs and examples

.gitignore

@@ -4,3 +4,4 @@ recipes
 venv
 .mypy_cache
 .vscode
+docs/book

docs/book.toml

@@ -0,0 +1,13 @@
+[book]
+authors = ["Emi Vasilek"]
+language = "en"
+multilingual = false
+title = "Comfy Recipes Documentation"
+
+[build]
+create-missing = true
+
+[output.html]
+preferred-dark-theme = "Ayu"
+git-repository-url = "https://codeberg.org/comfy.city/comfy-recipes"
+git-repository-icon = "fa-git"

docs/examples/firstrealrecipe.yaml

@@ -0,0 +1,15 @@
+title: Swedish Pancakes
+ingredients:
+  - 3 piece egg
+  - 1.25 cup milk
+  - 0.75 cup all purpose flour
+  - 1 tablespoon white sugar
+  - 1 tablespoon butter
+steps:
+  - Beat eggs in a bowl until the mixture is smooth.
+  - Add milk
+  - Mix flour, sugar and salt in a separate bowl
+  - Mix together with the egg mixture, mix until it's smooth
+  - heat a griddle
+  - Drop just enough of the mixture to the griddle to spread to all corners
+  - After about a minute, turn the pancake over

docs/examples/minimal.yaml

@@ -0,0 +1 @@
+- title: Pancakes

docs/examples/minimalusable.yaml

@@ -0,0 +1,5 @@
+- title: Pancakes
+  ingredients:
+    - 100 gram flour
+  steps:
+    - make pancakes

docs/src/SUMMARY.md

@@ -0,0 +1,14 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Installation](./installation.md)
+- [Tutorial](./tutorial/index.md)
+    - [Quick Start](./tutorial/quickstart.md)
+    - [Units](./tutorial/units.md)
+    - [Ingredients](./tutorial/ingredients.md)
+    - [Prices and Conversions](./tutorial/pricesconversions.md)
+- [Reference](./reference/index.md)
+    - [Recipe (recipes/*.yaml)](./reference/recipe.md)
+    - [Units (units.yaml)](./reference/units.md)
+    - [Ingredients (ingredients.yaml)](./reference/ingredients.md)
+    - [Settings (settings.yaml)](./reference/settings.md)

docs/src/installation.md

@@ -0,0 +1,14 @@
+# Installation
+## Docker
+The containers are available on <https://codeberg.org/comfy.city/-/packages/container/comfy-recipes/latest>
+```sh
+docker run --rm -v path/to/myrecipes:/mnt codeberg.org/comfy.city/comfy-recipes ARGUMENTS
+```
+
+for example:
+```sh
+docker run --rm -v path/to/myrecipes:/mnt codeberg.org/comfy.city/comfy-recipes build /mnt
+```
+
+---
+Docker is currently the only supported installation method, if you would like to use another method, please refer to the building instructions which are available in the project [README.md](https://codeberg.org/comfy.city/comfy-recipes/src/branch/main/README.md)

docs/src/introduction.md

@@ -0,0 +1,22 @@
+# Introduction
+
+Comfy Recipes is a program that allows you to create a rich collection of recipes and create a presentable website from them.
+
+## Get started
+If you don't have comfyrecipes installed yet, please see [Installation](./installation.md)
+
+1. write a recipe in a yaml format to `myrecipes/recipes/xxxx.yaml`, for example
+
+`🗎 myrecipes/recipes/pancakes.yaml:`
+```yaml
+{{#include ../examples/firstrealrecipe.yaml}}
+```
+
+2. run `comfyrecipes build myrecipes/` (this will build the website to `myrecipes/out/html`)
+3. run `comfyrecipes serve` myrecipes and navigate to <http://localhost:8000> (this will run a web server and allow you to see your rendered recipe)
+
+## Links
+* Repository: <https://codeberg.org/comfy.city/comfy-recipes>
+* Issues: <https://codeberg.org/comfy.city/comfy-recipes/issues>
+* Website: <https://comfy.city/comfy-recipes>
+* Documentation: <https://comfy.city/comfy-recipes/docs>

docs/src/reference/index.md

@@ -0,0 +1,15 @@
+# Reference
+
+* What's not marked as **MANDATORY** is optional.
+
+## Data Types
+* `string` - text of arbitrary length
+* `integer` - a whole number
+* `float` - a decimal number
+* `number` - `integer` or `float`
+
+## Table Of Contents
+* [Recipes](recipe.md) - documenting recipes/*.yaml
+* [Units](units.md) - documenting units.yaml
+* [Ingredients](ingredients.md) - documenting ingredients.yaml
+* [Settings](settings.md) - documenting settings.yaml

docs/src/reference/ingredients.md

@@ -0,0 +1,20 @@
+# Ingredients (ingredients.yaml)
+- list of [Ingredient](#ingredient)
+
+## Ingredient
+- name, **MANDATORY**, string
+- aliases, list of strings
+- wdid, integer
+- prices, list of [Prices](#price)
+- conversions, list of [Conversions](#conversion)
+
+## Price
+- price, **MANDATORY**, number
+- amount, **MANDATORY**, number
+- unit, **MANDATORY**, string, unit has to be listed in units.yaml if units.yaml exists
+- currency, string
+
+## Conversion
+- from, **MANDATORY**, string, from has to be listed in units.yaml if units.yaml exists
+- to, **MANDATORY**, string, to has to be listed in units.yaml if units.yaml exists
+- ratio, **MANDATORY**, number

docs/src/reference/recipe.md

@@ -0,0 +1,54 @@
+# Recipe (recipes/*.yaml)
+- title - **MANDATORY**, string
+- ingredients - list of [Simplified Ingredients](#simplified-ingredient) and [Ingredients](#ingredient)
+- steps - list of strings and [Steps Sections](#steps-section)
+- subrecipes - list of [Recipes](#recipe-recipesyaml)
+
+## Simplified Ingredient
+= string in a specific format
+```
+[amount unit] ingredient name [(note)]
+```
+[] means these sections are optional
+
+* `amount` - number
+* `unit` - a single word string
+* `name` - string with arbitrary content
+* `note` - string with arbitrary content, but has to be enclosed in parentheses, otherwise it will be considered to be part of `name`
+
+for example, valid values are:
+```
+1 piece carrot (sliced)
+^ amount
+  ^---^ unit
+        ^----^ ingredient name
+               ^-----^ note
+```
+```
+200 gram green onion
+^-^ amount
+    ^--^ unit
+         ^---------^ ingredient name
+```
+```
+apple
+^---^ ingredient name
+```
+```
+apple (red)
+^---^ ingredient name
+      ^---^ note
+```
+
+When amount and unit is not in the string, it is assumed to be `1 piece`.
+
+## Ingredient
+- name - **MANDATORY**, string, name has to be listed in ingredients.yaml if ingredients.yaml exists
+- amount - number
+- unit - string, unit has to be listed in units.yaml if units.yaml exists
+- or - list of [Ingredient](#ingredient)
+- note - string
+
+## Steps Section
+- section - **MANDATORY**, string, section name
+- steps - list of strings

docs/src/reference/settings.md

@@ -0,0 +1,2 @@
+# Settings (settings.yaml)
+* default_currency, string

docs/src/reference/units.md

@@ -0,0 +1,13 @@
+# Units (units.yaml)
+- list of [Units](#unit)
+
+## Unit
+- name, **MANDATORY**, string
+- conversions, list of [Conversions](#conversion)
+- aliases, list of strings
+
+## Conversion
+- to, **MANDATORY**, string, to has to be listed in units.yaml if units.yaml exists
+- ratio, **MANDATORY**, number
+
+(this is similar to [Ingredients Conversion](./ingredients.md#conversion), but the `from` field is automatically set to unit's name)

docs/src/tutorial/index.md

@@ -0,0 +1,21 @@
+# Tutorial
+
+This is the full file structure of comfy recipes input data:
+
+```
+- myrecipes/            - can be named according to your preference
+
+    - recipes/          - directory that will hold the recipes
+        - pancakes.yaml    - the individual recipe
+
+    - units.yaml        - OPTIONAL, file containing all valid units and their properties
+    - ingredients.yaml  - OPTIONAL, file containing all valid ingredients and their properties
+    - settings.yaml     - OPTIONAL, file for overriding default settings
+```
+
+In the following sub-chapters we will first create a simple recipe and then find out what each file does and what functionalities they can offer.
+
+- [Quick Start](./quickstart.md) - Creating simple recipes
+- [Units](./units.md) - What units.yaml is for and how to use it
+- [Ingredients](./ingredients.md) - Why list ingredients in ingredients.yaml and what it can offer
+- [Prices and Conversions](./pricesconversions.md) - Let's start adding and calculating prices of recipes

docs/src/tutorial/ingredients.md

@@ -0,0 +1,54 @@
+# Ingredients
+
+Similar to `units.yaml`, also `ingredients.yaml` is not a mandatory file, but having it gives us several advantages.
+* spelling mistakes are not silently ignored, if something is not listed in ingredients.yaml, comfyrecipes will warn you
+* we can use aliases - different names referring the same ingredient
+* we will be able to add some more data to ingredients that will allow us to calculate prices (described in [Prices and Conversions](./pricesconversions.md))
+
+```
+- myrecipes/
+    - recipes/
+        - pancakes.yaml
+    ...
+    - ingredients.yaml (we will be creating this file)
+```
+
+We will again use the final recipe from [Quick Start](quickstart.md).
+
+`🗎 myrecipes/recipes/pancakes.yaml:`
+```yaml
+{{#include ../../examples/firstrealrecipe.yaml}}
+```
+
+If you don't want to write the file manually, we can generate it using:
+```sh
+$ comfyrecipes generate-ingredients
+```
+
+This will generate a minimal ingredients.yaml:
+
+`🗎 myrecipes/ingredients.yaml:`
+```yaml
+- name: all purpose flour
+- name: butter
+- name: egg
+- name: milk
+- name: white sugar
+```
+
+Now, let's say we would want to call `all purpose flour` just `flour`, we can add an alias:
+
+`🗎 myrecipes/ingredients.yaml:`
+```yaml
+- name: all purpose flour
+  aliases:
+    - flour
+- name: butter
+- name: egg
+- name: milk
+- name: white sugar
+```
+
+Now whenever we add an ingredient called flour, it will be a reference to `all purpose flour`.
+
+For a full reference for what an ingredients yaml can contain, please see the [Ingredients Reference](../reference/ingredients.md)

docs/src/tutorial/pricesconversions.md

@@ -0,0 +1,27 @@
+# Prices and Conversions
+
+ComfyRecipes has the ability to compute recipe prices if we give it enough information.
+This requires your recipe collection to have an [`ingredients.yaml` file](./ingredients.md).
+Like with the previous sections, we will use
+
+# Settings
+
+Sometimes we need to configure some defaults globally, this is what settings.yaml is for.
+Currently it's only used for setting the default_currency.
+
+Let's create settings.yaml and set the default currency to USD.
+
+```
+- myrecipes/
+    - recipes/
+        - pancakes.yaml
+    ...
+    - settings.yaml
+```
+
+`🗎 myrecipes/settings.yaml:`
+```yaml
+default_currency: USD
+```
+
+For a full reference for what a settings yaml can contain, please see the [Settings Reference](../reference/settings.md)

docs/src/tutorial/quickstart.md

@@ -0,0 +1,65 @@
+# Quick Start
+
+Let's start writing recipes. First, create the directory structure that will hold all our input data.
+
+```
+- myrecipes/
+    - recipes/
+        - pancakes.yaml
+```
+
+Now when we have the structure created, let's create the most minimal possible `pancakes.yaml`:
+
+`🗎 myrecipes/recipes/pancakes.yaml:`
+```yaml
+{{#include ../../examples/minimal.yaml}}
+```
+
+And render it by running:
+```sh
+$ comfyrecipes build myrecipes
+```
+
+This will create a new directory `out/` in `myrecipes/` containing the built data.
+```
+- myrecipes/
+    - out/
+        - html/
+            - index.html
+            - pancakes.html
+    - recipes/
+        - pancakes.yaml
+```
+
+We can see the result if we start a web server pointing to that directory, for example by using:
+```sh
+$ comfyrecipes serve myrecipes
+```
+and navigate to <http://127.0.0.1:8000/>
+
+`serve` should NOT be used in production.
+
+While that was a valid recipe, it's not very useful and we can only see the title. Let's improve that:
+
+`🗎 myrecipes/recipes/pancakes.yaml:`
+```yaml
+{{#include ../../examples/minimalusable.yaml}}
+```
+
+* each ingredient is a step in the format `amount unit name`
+    * `amount` has to be a number
+    * `unit` has to be a single word
+    * `name` can be a string with arbitrary content
+    * for a full description of this format, please see the [Reference section](../reference/recipe.md#simplified-ingredient)
+* each step is a string with arbitrary content
+
+And again, build, make sure the server is running and navigate to <http://127.0.0.1:8000/>. From now on, we will assume you know how to build and serve your output directory.
+
+Once more, let's improve the recipe once again to something that can actually be made and is not just a demo. This does not introduce any new concepts compared to the last recipe we wrote.
+
+`🗎 myrecipes/recipes/pancakes.yaml:`
+```yaml
+{{#include ../../examples/firstrealrecipe.yaml}}
+```
+
+For a full reference for what a recipe yaml can contain, please see the [Recipe Reference](../reference/recipe.md)

docs/src/tutorial/units.md

@@ -0,0 +1,51 @@
+# Units
+
+Each recipe ingredient has a string unit assigned to it. This is great, but a centralized list of all alowed units with some additional properties has several advantages:
+
+* spelling mistakes are not silently ignored, if you make a mistake in the ingredient unit name, comfyrecipes will warn you that it's not on the units list
+* `gram` and `g` can refer to the same unit (using aliases)
+* we can tell comfyrecipes unit conversion rates (for example 1000 gram = 1 kilogram) which it can then use for example for calculating prices
+
+This example will use the final example from [Quick Start](quickstart.md).
+
+`🗎 myrecipes/recipes/pancakes.yaml:`
+```yaml
+{{#include ../../examples/firstrealrecipe.yaml}}
+```
+
+```
+- myrecipes/
+    - recipes/
+        - pancakes.yaml
+    ...
+    - units.yaml (we will be creating this file)
+```
+
+If you don't want to write the file manually, we can generate it using:
+```sh
+$ comfyrecipes generate-units
+```
+
+This will generate a minimal units.yaml:
+
+`🗎 myrecipes/units.yaml:`
+```yaml
+- name: cup
+- name: piece
+- name: tablespoon
+```
+
+Now, let's say we would want to call `tablespoon` just `tbsp`, we can add an alias:
+
+`🗎 myrecipes/units.yaml:`
+```yaml
+- name: cup
+- name: piece
+- name: tablespoon
+  aliases:
+    - tbsp
+```
+
+Now we can rename the `tablespoon` unit in the recipe to `tbsp` and it will reference the `tablespoon` unit.
+
+For a full reference for what a recipe yaml can contain, please see the [Units Reference](../reference/units.md)