added more documentation

This commit is contained in:
vabene1111 2021-01-06 00:17:53 +01:00
parent fd8229684c
commit caa33810c4
4 changed files with 116 additions and 0 deletions

View File

@ -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.

View File

@ -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[<index in list>] }}` 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.

View File

@ -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<br />- write comments <br />- 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<br />- 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.

View File

@ -28,6 +28,10 @@ nav:
- Kubernetes: install/kubernetes.md - Kubernetes: install/kubernetes.md
- Manual: install/manual.md - Manual: install/manual.md
- Other setups: install/other.md - Other setups: install/other.md
- Features:
- Tempalating: features/templating.md
- Storages and Sync: features/external_recipes.md
- System: - System:
- Updating: system/updating.md - Updating: system/updating.md
- Permission System: system/permissions.md
- Backup: system/backup.md - Backup: system/backup.md