From 3e46ae89b0cf815fde2f3afd4496fa8128236d25 Mon Sep 17 00:00:00 2001 From: Emi Vasilek Date: Tue, 28 Nov 2023 12:29:49 +0000 Subject: [PATCH] add docs and examples --- .gitignore | 1 + docs/book.toml | 13 ++++++ docs/examples/firstrealrecipe.yaml | 15 ++++++ docs/examples/minimal.yaml | 1 + docs/examples/minimalusable.yaml | 5 ++ docs/src/SUMMARY.md | 14 ++++++ docs/src/installation.md | 14 ++++++ docs/src/introduction.md | 22 +++++++++ docs/src/reference/index.md | 15 ++++++ docs/src/reference/ingredients.md | 20 ++++++++ docs/src/reference/recipe.md | 54 +++++++++++++++++++++ docs/src/reference/settings.md | 2 + docs/src/reference/units.md | 13 ++++++ docs/src/tutorial/index.md | 21 +++++++++ docs/src/tutorial/ingredients.md | 54 +++++++++++++++++++++ docs/src/tutorial/pricesconversions.md | 27 +++++++++++ docs/src/tutorial/quickstart.md | 65 ++++++++++++++++++++++++++ docs/src/tutorial/units.md | 51 ++++++++++++++++++++ 18 files changed, 407 insertions(+) create mode 100644 docs/book.toml create mode 100644 docs/examples/firstrealrecipe.yaml create mode 100644 docs/examples/minimal.yaml create mode 100644 docs/examples/minimalusable.yaml create mode 100644 docs/src/SUMMARY.md create mode 100644 docs/src/installation.md create mode 100644 docs/src/introduction.md create mode 100644 docs/src/reference/index.md create mode 100644 docs/src/reference/ingredients.md create mode 100644 docs/src/reference/recipe.md create mode 100644 docs/src/reference/settings.md create mode 100644 docs/src/reference/units.md create mode 100644 docs/src/tutorial/index.md create mode 100644 docs/src/tutorial/ingredients.md create mode 100644 docs/src/tutorial/pricesconversions.md create mode 100644 docs/src/tutorial/quickstart.md create mode 100644 docs/src/tutorial/units.md diff --git a/.gitignore b/.gitignore index dc14d49..4293add 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ recipes venv .mypy_cache .vscode +docs/book diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 0000000..f1796db --- /dev/null +++ b/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" diff --git a/docs/examples/firstrealrecipe.yaml b/docs/examples/firstrealrecipe.yaml new file mode 100644 index 0000000..e5dcd4d --- /dev/null +++ b/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 diff --git a/docs/examples/minimal.yaml b/docs/examples/minimal.yaml new file mode 100644 index 0000000..91aa1ab --- /dev/null +++ b/docs/examples/minimal.yaml @@ -0,0 +1 @@ +- title: Pancakes diff --git a/docs/examples/minimalusable.yaml b/docs/examples/minimalusable.yaml new file mode 100644 index 0000000..103d032 --- /dev/null +++ b/docs/examples/minimalusable.yaml @@ -0,0 +1,5 @@ +- title: Pancakes + ingredients: + - 100 gram flour + steps: + - make pancakes diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 0000000..fba6588 --- /dev/null +++ b/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) diff --git a/docs/src/installation.md b/docs/src/installation.md new file mode 100644 index 0000000..565b855 --- /dev/null +++ b/docs/src/installation.md @@ -0,0 +1,14 @@ +# Installation +## Docker +The containers are available on +```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) diff --git a/docs/src/introduction.md b/docs/src/introduction.md new file mode 100644 index 0000000..d7343de --- /dev/null +++ b/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 (this will run a web server and allow you to see your rendered recipe) + +## Links +* Repository: +* Issues: +* Website: +* Documentation: diff --git a/docs/src/reference/index.md b/docs/src/reference/index.md new file mode 100644 index 0000000..e714285 --- /dev/null +++ b/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 diff --git a/docs/src/reference/ingredients.md b/docs/src/reference/ingredients.md new file mode 100644 index 0000000..3a0a115 --- /dev/null +++ b/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 diff --git a/docs/src/reference/recipe.md b/docs/src/reference/recipe.md new file mode 100644 index 0000000..437f8f6 --- /dev/null +++ b/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 diff --git a/docs/src/reference/settings.md b/docs/src/reference/settings.md new file mode 100644 index 0000000..0a8bd35 --- /dev/null +++ b/docs/src/reference/settings.md @@ -0,0 +1,2 @@ +# Settings (settings.yaml) +* default_currency, string diff --git a/docs/src/reference/units.md b/docs/src/reference/units.md new file mode 100644 index 0000000..bd1eaa0 --- /dev/null +++ b/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) diff --git a/docs/src/tutorial/index.md b/docs/src/tutorial/index.md new file mode 100644 index 0000000..7fc531a --- /dev/null +++ b/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 diff --git a/docs/src/tutorial/ingredients.md b/docs/src/tutorial/ingredients.md new file mode 100644 index 0000000..5c1deb0 --- /dev/null +++ b/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) diff --git a/docs/src/tutorial/pricesconversions.md b/docs/src/tutorial/pricesconversions.md new file mode 100644 index 0000000..ca72e8f --- /dev/null +++ b/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) diff --git a/docs/src/tutorial/quickstart.md b/docs/src/tutorial/quickstart.md new file mode 100644 index 0000000..b49663d --- /dev/null +++ b/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 + +`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 . 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) diff --git a/docs/src/tutorial/units.md b/docs/src/tutorial/units.md new file mode 100644 index 0000000..5f73ecb --- /dev/null +++ b/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)