documentation rework + developer updates
This commit is contained in:
Hayden
parent
8dc7f0663d
commit
f33f90ad5d
14 changed files with 129 additions and 47 deletions
3
docs/docs/api/api-intro.md
Normal file
3
docs/docs/api/api-intro.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# API Introduction
|
||||
|
||||
TODO
|
||||
|
|
@ -1,26 +1,22 @@
|
|||
# Contributing to Mealie
|
||||
We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
|
||||
|
||||
- Reporting a bug
|
||||
- Discussing the current state of the code
|
||||
- Submitting a fix
|
||||
- Proposing new features
|
||||
- Becoming a maintainer
|
||||
!!! Warning
|
||||
It should be known going into this that this is my first open source project, and my first public github repo I'm actively managing. If something does not make sense, or is not best practice. PLEASE feel free to reach out and let me know. I'm all about improving workflow and making it easier for contributors.
|
||||
|
||||
[Remember to join the Discord and stay in touch with other developers working on the project](https://discord.gg/R6QDyJgbD2)!
|
||||
[Please Join the Discord](https://discord.gg/R6QDyJgbD2). We are building a community of developers working on the project.
|
||||
|
||||
## We Develop with Github
|
||||
We use github to host code, to track issues and feature requests, as well as accept pull requests.
|
||||
|
||||
## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests
|
||||
Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests:
|
||||
Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests:
|
||||
|
||||
1. Fork the repo and create your branch from `master`.
|
||||
1. Fork the repo and create your branch from `dev`.
|
||||
2. Read the page in in [dev/dev-notes.md](https://github.com/hay-kot/mealie/blob/0.1.0/dev/dev-notes.md) to get an idea on where the project is at.
|
||||
3. If you've changed APIs, update the documentation.
|
||||
4. Make sure your code lints.
|
||||
3. If you're interested on working on major changes please get in touch on discord and coordinate with other developers. No sense in doubling up on work if someones already on it.
|
||||
4. If you've changed APIs, update the documentation.
|
||||
5. Issue that pull request!
|
||||
6. If you make changes to the dev/0.1.0 branch reflect those changes in the dev/dev-notes.md to keep track of changes.
|
||||
6. If you make changes to the dev branch reflect those changes in the dev/dev-notes.md to keep track of changes. Don't forget to add your name/handle/identifier!
|
||||
|
||||
## Any contributions you make will be under the MIT Software License
|
||||
In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
# Guidelines
|
||||
|
||||
TODO
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
# Development: Getting Started
|
||||
|
||||
After reading through the [Code Contributions Guide](http://127.0.0.1:8000/contributors/developers-guide/code-contributions/) and forking the repo you can start working. This project is developed with :whale: docker and as such you will be greatly aided by using docker for development. It's not necessary but it is helpful.
|
||||
|
||||
## With Docker
|
||||
There are 2 scripts to help set up your development environment in dev/scripts/.
|
||||
|
||||
`docker-compose.dev.sh` - Will spin up a docker development server
|
||||
`docker-compose.sh` - Will spin up a docker production server
|
||||
|
||||
There are VSCode tasks created in the .vscode folder. You can use these to quickly execute the scripts above using the command palette.
|
||||
|
||||
|
||||
## Without Docker
|
||||
?? TODO
|
||||
|
||||
## Trouble Shooting
|
||||
|
||||
!!! Error "Symptom: Vue Development Server Wont Start"
|
||||
**Error:** `TypeError: Cannot read property 'upgrade' of undefined`
|
||||
|
||||
**Solution:** You may be missing the `/frontend/.env.development.` The contents should be `VUE_APP_API_BASE_URL=http://127.0.0.1:9921`. This is a reference to proxy the the API requests from Vue to 127.0.0.1 at port 9921 where FastAPI should be running.
|
||||
|
||||
!!! Error "Symptom: FastAPI Development Server Wont Start"
|
||||
**Error:** `RuntimeError: Directory '/app/dist' does not exist`
|
||||
|
||||
**Solution:** Create an empty /mealie/dist directory. This directory is served as static content by FastAPI. It is provided during the build process and may be missing in development.
|
||||
|
||||
Run into another issue? [Ask for help on discord](https://discord.gg/R6QDyJgbD2)
|
||||
15
docs/docs/contributors/non-coders.md
Normal file
15
docs/docs/contributors/non-coders.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
# Non-Code Contributions
|
||||
|
||||
We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
|
||||
|
||||
- Reporting a bug
|
||||
- Discussing the current state of the code
|
||||
- Submitting a fix
|
||||
- Proposing new features
|
||||
- Becoming a maintainer
|
||||
|
||||
[Remember to join the Discord and stay in touch with other developers working on the project](https://discord.gg/R6QDyJgbD2)!
|
||||
|
||||
Additionally, you can buy me a coffee and support the project. When I get financial support it helps me know that there's real interest in the project and that it's worth the time to keep developing.
|
||||
|
||||
<a href="https://www.buymeacoffee.com/haykot" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-green.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
|
||||
|
|
@ -1,19 +1,5 @@
|
|||
# Site Settings Panel
|
||||
!!! danger
|
||||
As this is still a **BETA** It is recommended that you backup your data often and store in more than one place. Ad-hear to backup best practices with the [3-2-1 Backup Rule](https://en.wikipedia.org/wiki/Backup)
|
||||
|
||||
|
||||
## Theme Settings
|
||||
Color themes can be created and set from the UI in the settings page. You can select an existing color theme or create a new one. On creation of a new color theme random colors will first be generated, then you can select and save as you'd like. By default the "default" theme will be loaded for all new users visiting the site. All created color themes are available to all users of the site. Separate color themes can be set for both Light and Dark modes.
|
||||
|
||||
|
||||
|
||||
!!! note
|
||||
Theme data is stored in cookies in the browser. Calling "Save Theme" will refresh the cookie with the selected theme as well save the theme to the database.
|
||||
|
||||
|
||||
## Backup and Export
|
||||
|
||||
# Backup and Export
|
||||
|
||||
|
||||
All recipe data can be imported and exported as necessary from the UI. Under the admin page you'll find the section for using Backups and Exports.
|
||||
|
||||
|
|
@ -21,10 +7,10 @@ To create an export simple add the tag and the markdown template and click Backu
|
|||
|
||||
To import a backup it must be in your backups folder. If it is in the backup folder it will automatically show up as an source to restore from. Selected the desired backup and import the backup file.
|
||||
|
||||
### Custom Templating
|
||||
## Custom Templating
|
||||
On export you can select a template to use to render files using the jinja2 syntax. This can be done to export recipes in other formats besides regular .json.Look at this example for rendering a markdown recipe using the jinja2 syntax.
|
||||
|
||||
#### Input
|
||||
### Input
|
||||
```jinja2
|
||||
|
||||
|
||||
|
|
@ -52,7 +38,7 @@ Categories: {{ recipe.categories }}
|
|||
Original URL: {{ recipe.orgURL }}
|
||||
```
|
||||
|
||||
#### Output
|
||||
### Output
|
||||
```markdown
|
||||
|
||||
|
||||
|
|
@ -90,14 +76,4 @@ Categories: []
|
|||
Original URL: https://www.bonappetit.com/recipe/five-spice-popcorn-chicken#intcid=_bon-appetit-recipe-bottom-recirc_3cad5ce9-734a-46f8-b503-78c33d2e7279_similar2-3
|
||||
```
|
||||
|
||||
If you decide you don't like mealie. This is a good way to export into a format that can be imported into another.
|
||||
|
||||
|
||||
## Meal Planner Webhooks
|
||||
Meal planner webhooks are post requests sent from Mealie to an external endpoint. The body of the message is the Recipe JSON of the scheduled meal. If no meal is schedule, no request is sent. The webhook functionality can be enabled or disabled as well as scheduled. Note that you must "Save Webhooks" prior to any changes taking affect server side.
|
||||
|
||||
## Migration
|
||||
|
||||
### Chowdown
|
||||
|
||||
In the Admin page on the in the Migration section you can provide a URL for a repo hosting a Chowdown site and Mealie will pull the images and recipes from the instance and automatically import them into the database. Due to the nature of the yaml format you may have mixed results but you should get an error report of the recipes that had errors and will need to be manually added. Note that you can only import the repo as a whole. You cannot import individual recipes.
|
||||
If you decide you don't like mealie. This is a good way to export into a format that can be imported into another.
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Getting Started
|
||||
# Installation
|
||||
To deploy docker on your local network it is highly recommended to use docker to deploy the image straight from dockerhub. Using the docker-compose below you should be able to get a stack up and running easily by changing a few default values and deploying. Currently the only supported database is Mongo. Mealie is looking for contributors to support additional databases.
|
||||
|
||||
|
||||
|
|
@ -8,4 +8,4 @@ To edit the meal in a meal plan simply select the edit button on the card in the
|
|||
!!! warning
|
||||
In coming a future release recipes for meals will be restricted to specific categories.
|
||||
|
||||
|
||||
|
||||
12
docs/docs/getting-started/migration-imports.md
Normal file
12
docs/docs/getting-started/migration-imports.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# Migration
|
||||
|
||||
### Chowdown
|
||||
|
||||
In the Admin page on the in the Migration section you can provide a URL for a repo hosting a [Chowdown](https://github.com/clarklab/chowdown) repository and Mealie will pull the images and recipes from the instance and automatically import them into the database. Due to the nature of the yaml format you may have mixed results but you should get an error report of the recipes that had errors and will need to be manually added. Note that you can only import the repo as a whole. You cannot import individual recipes.
|
||||
|
||||
We'd like to support additional migration paths. [See open issues.](https://github.com/hay-kot/mealie/issues)
|
||||
|
||||
**Currently Proposed Are:**
|
||||
|
||||
- NextCloud Recipes
|
||||
- Open Eats
|
||||
|
|
@ -4,7 +4,7 @@
|
|||
Adding a recipe can be as easy as copying the recipe URL into mealie and letting the web scrapper try to pull down the information. Currently this scraper is implemented with [scrape-schema-recipe package](https://pypi.org/project/scrape-schema-recipe/). You may have mixed results on some websites, especially with blogs or non specific recipe websites. See the bulk import Option below for another a convenient way to add blog style recipes into Mealie.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Recipe Editor
|
||||
|
|
@ -12,12 +12,12 @@ Recipes can be edited and created via the UI. This is done with both a form base
|
|||
|
||||
You can also add a custom recipe with the UI editor built into the web view. After logging in as a user you'll have access to the editor to make changes to all the content in the recipe.
|
||||
|
||||
|
||||
|
||||
|
||||
## Bulk Import
|
||||
Mealie also supports bulk import of recipe instructions and ingredients. Select "Bulk Add" in the editor and paste in your plain text data to be parsed. Each line is treated as one entry and will be appended to the existing ingredients or instructions if they exist. Empty lines will be stripped from the text.
|
||||
|
||||
|
||||
|
||||
|
||||
## Schema
|
||||
Recipes are stored in the json-like format in mongoDB and then sent and edited in json format on the frontend. Each recipes uses [Recipe Schema](https://schema.org/Recipe) as a general guide with some additional properties specific to Mealie.
|
||||
21
docs/docs/getting-started/site-settings.md
Normal file
21
docs/docs/getting-started/site-settings.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
# Site Settings Panel
|
||||
!!! danger
|
||||
As this is still a **BETA** It is recommended that you backup your data often and store in more than one place. Ad-hear to backup best practices with the [3-2-1 Backup Rule](https://en.wikipedia.org/wiki/Backup)
|
||||
|
||||
|
||||
## Theme Settings
|
||||
Color themes can be created and set from the UI in the settings page. You can select an existing color theme or create a new one. On creation of a new color theme random colors will first be generated, then you can select and save as you'd like. By default the "default" theme will be loaded for all new users visiting the site. All created color themes are available to all users of the site. Separate color themes can be set for both Light and Dark modes.
|
||||
|
||||
|
||||
|
||||
!!! note
|
||||
Theme data is stored in cookies in the browser. Calling "Save Theme" will refresh the cookie with the selected theme as well save the theme to the database.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Meal Planner Webhooks
|
||||
Meal planner webhooks are post requests sent from Mealie to an external endpoint. The body of the message is the Recipe JSON of the scheduled meal. If no meal is schedule, no request is sent. The webhook functionality can be enabled or disabled as well as scheduled. Note that you must "Save Webhooks" prior to any changes taking affect server side.
|
||||
|
||||
|
||||
|
|
@ -1,19 +1,46 @@
|
|||
site_name: Mealie Docs
|
||||
|
||||
theme:
|
||||
favicon: img/favicon.png
|
||||
name: material
|
||||
icon:
|
||||
logo: material/silverware-variant
|
||||
features:
|
||||
- navigation.expand
|
||||
- navigation.instant
|
||||
|
||||
markdown_extensions:
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:materialx.emoji.twemoji
|
||||
emoji_generator: !!python/name:materialx.emoji.to_svg
|
||||
- def_list
|
||||
- pymdownx.highlight
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- admonition
|
||||
|
||||
extra_css:
|
||||
- stylesheets/custom.css
|
||||
repo_url: https://github.com/hay-kot/mealie
|
||||
repo_name: hay-kot/mealie
|
||||
|
||||
nav:
|
||||
- About The Project: "index.md"
|
||||
- Getting Started:
|
||||
- Installation: "getting-started/install.md"
|
||||
- Working With Recipes: "getting-started/recipes.md"
|
||||
- Planning Meals: "getting-started/meal-planner.md"
|
||||
- Site Settings: "getting-started/site-settings.md"
|
||||
- Backups and Exports: "getting-started/backups-and-exports.md"
|
||||
- Recipe Migration: "getting-started/migration-imports.md"
|
||||
- API Reference:
|
||||
- Swagger/OpenAPI: "api/api-intro.md"
|
||||
- Contributors Guide:
|
||||
- Non-Code: "contributors/non-coders.md"
|
||||
- Developers Guide:
|
||||
- Code Contributions: "contributors/developers-guide/code-contributions.md"
|
||||
- Dev Getting Started: "contributors/developers-guide/starting-dev-server.md"
|
||||
- Guidelines: "contributors/developers-guide/general-guidelines.md"
|
||||
- Development Road Map: "roadmap.md"
|
||||
- Change Log: "changelog.md"
|
||||
|
|
|
|||
Loading…
Reference in a new issue