diff --git a/docs/features/external_recipes.md b/docs/features/external_recipes.md new file mode 100644 index 00000000..382eabf5 --- /dev/null +++ b/docs/features/external_recipes.md @@ -0,0 +1,36 @@ +The original intend of this application was to provide a search interface to my large collection of PDF scans of recipes. +This feature is now called External recipes. + +!!! info + Internal recipes are stored in a structured manner inside the database. They can be displayed using the standardized + interface and support features like shopping lists, scaling and steps. + External recipes are basically files that are displayed within the interface. The benefit is that you can quickly + import all your old recipes and convert them one by one. + +To use external recipes you will first need to configure a storage source. After that a synced path can be created. +Lastly you will need to sync with the external path and import recipes you desire. + +# Storage Backends +!!! success + Currently only Nextcloud and Dropbox are supported. There are plans to add more provider + +A `Storage Backend` is a remote storage location where files are **read** from. +To add a new backend click on `Storage Data` and then on `Storage Backends`. +There click the plus button. + +Enter a name (just a display name for you to identify it) and an API access Token for the account you want to use. +Dropboxes API tokens can be found on the +[Dropboxes API explorer](https://dropbox.github.io/dropbox-api-v2-explorer/#auth_token/from_oauth1) +with the button on the top right. For Nextcloud, you can use an App password created in the settings. + +## Adding Synced Paths +To add a new path from your Storage backend to the sync list, go to `Storage Data >> Configure Sync` and +select the storage backend you want to use. +Then enter the path you want to monitor starting at the storage root (e.g. `/Folder/RecipesFolder`) and save it. + +## Syncing Data +To sync the recipes app with the storage backends press `Sync now` under `Storage Data >> Configure Sync`. + +## Discovered Recipes +All files found by the sync can be found under `Manage Data >> Discovered recipes`. +There you can either import all at once without modifying them or import one by one, adding tags while importing. diff --git a/docs/features/templating.md b/docs/features/templating.md new file mode 100644 index 00000000..60f9e9cd --- /dev/null +++ b/docs/features/templating.md @@ -0,0 +1,42 @@ +With the Version `0.14.0` support for using a custom Jinja2 Template in recipe step instructions has been added. + +This allows you to write ingredients with their corresponding amount directly inside the text while still profiting +from recipe scaling. + +![2021-01-05_22-26](https://user-images.githubusercontent.com/6819595/103701386-3e1a2b80-4fa6-11eb-93d1-6257e65bb5b1.gif) + +!!! info + Templating is a very new feature and still WIP. Feel free to open an issue to provide feedback and ideas. + Please also refer to [Issue #218](https://github.com/vabene1111/recipes/issues/218) where this feature has been discussed. + +## Using Templating +Currently the only available variable in the Templating context is `ingredients`. + +`ingredients` is an array that contains all ingredients of the current recipe step. You can access an ingredient by using +`{{ ingredient[] }}` where the index refers to the position in the list of ingredients starting with zero. +You can also use the interaction menu of the ingredient to copy its reference. + +!!! warning + Please note that changing the order of the ingredients will break the reference (or at least make it useless). + See the technical reasoning for more information on why it is this way. + +![image](https://user-images.githubusercontent.com/6819595/103709654-5d6b8580-4fb3-11eb-9d04-36ab5a993f90.png) + +You can also access only the amount, unit, note or food inside your instruction text using +``` +{{ instructions[0].amount }} +{{ instructions[0].unit }} +{{ instructions[0].food }} +{{ instructions[0].note }} +``` + +## Technical Reasoning +There are several options how the ingredients in the list can be related to the Template Context in the Text. + +The template could access them by ID, the food name or the position in the list. All options have their benefits and disadvantages. + +1. **ID**: ugly to write and read when not rendered and also more complex from a technical standpoint +2. **Name**: very nice to read and easy but does not work when a food occurs twice in a step. Could have workaround but would then be inconsistent. +3. **Position**: easy to write and understand but breaks when ordering is changed and not really nice to read when instructions are not rendered. + +I decided to go for the position based system. If you know of any better way feel free to open an issue or PR. \ No newline at end of file diff --git a/docs/system/permissions.md b/docs/system/permissions.md new file mode 100644 index 00000000..bdf34073 --- /dev/null +++ b/docs/system/permissions.md @@ -0,0 +1,34 @@ +!!! danger "WIP" + This application was developed for private use in a trusted environment. + Due to popular demand a basic permission system has been added. + It does its job protecting the most critical parts of the application, but it is **not yet recommended** to + give accounts to completely untrusted users. + Work is done to improve the permission system, but it's not yet fully done and tested. + +## Permission levels +The following table roughly defines the capabilities of each role + +| Group | Capabilities | +| ---------------- | ------------------------------------------------------------ | +| logged in user | Can do almost nothing without a group. | +| guest | - Search and view recipes
- write comments
- change user settings (e.g. language, theme, password) | +| user | Can do basically everything except for what admins can do | +| admin | - Create, edit and delete external storage
- Create, edit and delete synced paths | +| django superuser | Ignores all permission checks and can access admin interface | + +## Creating User accounts + +!!! warning + Users without groups cannot do anything. Make sure to assign them a group! + +You can either create new users trough the admin interface or by sending them invite links. + +Invite links can be generated on the System page. If you specify a username during the creation of the link +the person using it won't be able to change that name. + +## Managing Permissions +Management of permissions can currently only be achieved trough the django admin interface. + +!!! warning + Please do not rename the groups as this breaks the permission system. + diff --git a/mkdocs.yml b/mkdocs.yml index 0bf24305..e42eb92e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,6 +28,10 @@ nav: - Kubernetes: install/kubernetes.md - Manual: install/manual.md - Other setups: install/other.md + - Features: + - Tempalating: features/templating.md + - Storages and Sync: features/external_recipes.md - System: - Updating: system/updating.md + - Permission System: system/permissions.md - Backup: system/backup.md \ No newline at end of file