mirror of
https://github.com/TandoorRecipes/recipes.git
synced 2025-12-24 02:39:20 -05:00
readme and documentation
This commit is contained in:
vabene1111
68
README.md
68
README.md
@@ -7,27 +7,27 @@
|
||||
Recipes is a Django application to manage, tag and search recipes using either built-in models or
|
||||
external storage providers hosting PDF's, images or other files.
|
||||
|
||||
|
||||
[Installation Instructions](https://vabene1111.github.io/recipes/install/docker/) - [Documentation](https://vabene1111.github.io/recipes/) - [More (slightly outdated) Screenshots](https://imgur.com/a/V01151p)
|
||||
|
||||
[More Screenshots](https://imgur.com/a/V01151p)
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
- :package: **Sync** files with Dropbox and Nextcloud (more can easily be added)
|
||||
- :mag: Powerful **search** with Django's [TrigramSimilarity](https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/search/#trigram-similarity)
|
||||
- :label: Create and search for **tags**, assign them in batch to all files matching certain filters
|
||||
- :page_facing_up: **Create recipes** locally within a nice, standardized web interface
|
||||
- :arrow_down: **Import recipes** from thousands of websites supporting [ld+json or microdata](https://schema.org/Recipe)
|
||||
- :iphone: Optimized for use on **mobile** devices like phones and tablets
|
||||
- :shopping_cart: Generate **shopping** lists from recipes
|
||||
- :calendar: Create a **plan** on what to eat when
|
||||
- :family: **Share** recipes with friends and comment on them to suggest or remember changes you made
|
||||
- :heavy_division_sign: Automatically convert decimal units to **fractions** for those who like this
|
||||
- :whale: Easy setup with **Docker**
|
||||
- :art: Customize your interface with **themes**
|
||||
- :envelope: Export and import recipes from other users
|
||||
- :earth_africa: Localized in many languages thanks to the awesome community
|
||||
- :heavy_plus_sign: Many more like recipe scaling, image compression, cookbooks, printing views, ...
|
||||
- 📦 **Sync** files with Dropbox and Nextcloud (more can easily be added)
|
||||
- 🔍 Powerful **search** with Djangos [TrigramSimilarity](https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/search/#trigram-similarity)
|
||||
- 🏷️ Create and search for **tags**, assign them in batch to all files matching certain filters
|
||||
- 📄 **Create recipes** locally within a nice, standardized web interface
|
||||
- ⬇️ **Import recipes** from thousands of websites supporting [ld+json or microdata](https://schema.org/Recipe)
|
||||
- 📱 Optimized for use on **mobile** devices like phones and tablets
|
||||
- 🛒 Generate **shopping** lists from recipes
|
||||
- 📆 Create a **Plan** on what to eat when
|
||||
- 👪 **Share** recipes with friends and comment on them to suggest or remember changes you made
|
||||
- ➗ automatically convert decimal units to **fractions** for those who like this
|
||||
- 🐳 Easy setup with **Docker** and included examples for Kubernetes, Unraid and Synology
|
||||
- 🎨 Customize your interface with **themes**
|
||||
- ✉️ Export and import recipes from other users
|
||||
- 🌍 localized in many languages thanks to the awesome community
|
||||
- ➕ Many more like recipe scaling, image compression, cookbooks, printing views, ...
|
||||
|
||||
This application is meant for people with a collection of recipes they want to share with family and friends or simply
|
||||
store them in a nicely organized way. A basic permission system exists but this application is not meant to be run as
|
||||
@@ -37,40 +37,18 @@ Documentation can be found [here](https://github.com/vabene1111/recipes/wiki).
|
||||
While this application has been around for a while and is actively used by many (including myself), it is still considered
|
||||
**beta** software that has a lot of rough edges and unpolished parts.
|
||||
|
||||
## Installation
|
||||
Please refer to the Installation section of the [Documentation](https://vabene1111.github.io/recipes/).
|
||||
|
||||
## Contributing
|
||||
|
||||
Pull Requests and ideas are welcome, feel free to contribute in any way.
|
||||
|
||||
**If you want, feel free to open an issue or pull request to add yourself to the list of awesome contributors.**
|
||||
|
||||
### Getting Started
|
||||
This application is developed using the Django framework for Python. They have excellent
|
||||
[documentation](https://www.djangoproject.com/start/) on how to get started, so I will only give you the basics here.
|
||||
|
||||
1. Clone this repository wherever you like and install the Python language for your OS (at least version 3.8)
|
||||
2. Open it in your favorite editor/IDE (e.g. PyCharm)
|
||||
1. If you want, create a virutal environment for all your packages.
|
||||
3. Install all required packages: `pip install -r requirements.txt`
|
||||
4. Run the migrations: `python manage.py migrate`
|
||||
5. Start the development server: `python manage.py runserver`
|
||||
|
||||
There is **no** need to set any environment variables. By default, a simple sqlite database is used and all settings are
|
||||
populated from default values.
|
||||
|
||||
### Translating
|
||||
|
||||
There is a [transifex project](https://www.transifex.com/django-recipes/django-cookbook/) project to enable community driven translations. If you want to contribute a new language or help maintain an already existing one feel free to create a transifex account (using the link above) and request to join the project.
|
||||
|
||||
It is also possible to provide the translations directly by creating a new language using `manage.py makemessages -l <language_code> -i venv`. Once finished, simply open a PR with the changed files.
|
||||
## Documentation
|
||||
Please refer to the [documentation](https://vabene1111.github.io/recipes/) for everything you need to know.
|
||||
|
||||
## License
|
||||
|
||||
Beginning with version 0.10.0 the code in this repository is licensed under the [GNU AGPL v3](https://www.gnu.org/licenses/agpl-3.0.de.html) license with an
|
||||
[common clause](https://commonsclause.com/) selling exception. See [LICENSE.md](https://github.com/vabene1111/recipes/blob/develop/LICENSE.md) for details.
|
||||
|
||||
> NOTE: There appears to be a whole range of legal issues with licensing anything else then the standard completely open licenses.
|
||||
> I am in the process of getting some professional legal advice to sort out these issues.
|
||||
> Please also see [Issue 238](https://github.com/vabene1111/recipes/issues/238) for some discussion and **reasoning** regarding the topic.
|
||||
|
||||
**Reasoning**
|
||||
**This software and *all* its features are and will always be free for everyone to use and enjoy.**
|
||||
|
||||
|
||||
46
docs/contribute.md
Normal file
46
docs/contribute.md
Normal file
@@ -0,0 +1,46 @@
|
||||
If you like this application and want it to improve, feel free to contribute to its development.
|
||||
|
||||
!!! success "Contribution List"
|
||||
If you help bring this project forward you deserve to be credited for it.
|
||||
Feel free to add yourself to `CONTRIBUTERS.md` or message me to add you if you have contributed anything.
|
||||
|
||||
## Issues
|
||||
The most basic but also very important way of contributing is reporting issues and commenting on ideas and feature requests
|
||||
over on the GitHub issues.
|
||||
|
||||
Without Feedback improvement can't happen, so don't hesitate to say what you want to say.
|
||||
|
||||
## Contributing Code
|
||||
Code contributions are always welcome. There is no special rules for what you need to do,
|
||||
just do your best and we will work together to get your idea and code merged into the project.
|
||||
|
||||
### Getting Started
|
||||
This application is developed using the Django framework for Python. They have excellent
|
||||
[documentation](https://www.djangoproject.com/start/) on how to get started, so I will only give you the basics here.
|
||||
|
||||
1. Clone this repository wherever you like and install the Python language for your OS (at least version 3.8)
|
||||
2. Open it in your favorite editor/IDE (e.g. PyCharm)
|
||||
1. If you want, create a virutal environment for all your packages.
|
||||
3. Install all required packages: `pip install -r requirements.txt`
|
||||
4. Run the migrations: `python manage.py migrate`
|
||||
5. Start the development server: `python manage.py runserver`
|
||||
|
||||
There is **no** need to set any environment variables. By default, a simple sqlite database is used and all settings are
|
||||
populated from default values.
|
||||
|
||||
### Contribute Translations
|
||||
|
||||
If you know any foreign languages that is not yet translated feel free to contribute translations.
|
||||
|
||||
There is a [transifex project](https://www.transifex.com/django-recipes/django-cookbook/) project where you can get started.
|
||||
If you want to contribute a new language or help maintain an already existing one feel free to create a transifex
|
||||
account (using the link above) and request to join the project.
|
||||
|
||||
!!! warning "Transifex Requests"
|
||||
The Team management, language creation and communication on transifex is very difficult for some reason.
|
||||
Because of this please have some patience when approving your requests or adding you to a team takes a while.
|
||||
Please also not that if you request a language you are not automatically in its translation team and you will
|
||||
need to make **an additional request** after I have accepted the language.
|
||||
|
||||
It is also possible to provide the translations directly by creating a new language
|
||||
using `manage.py makemessages -l <language_code> -i venv`. Once finished, simply open a PR with the changed files.
|
||||
@@ -20,9 +20,33 @@ The recipe manager that allows you to manage your ever growing collection of dig
|
||||
- 📆 Create a **Plan** on what to eat when
|
||||
- 👪 **Share** recipes with friends and comment on them to suggest or remember changes you made
|
||||
- ➗ automatically convert decimal units to **fractions** for those who like this
|
||||
- 🐳 Easy setup with **Docker**
|
||||
- 🐳 Easy setup with **Docker** and included examples for Kubernetes, Unraid and Synology
|
||||
- 🎨 Customize your interface with **themes**
|
||||
- ✉️ Export and import recipes from other users
|
||||
- 🌍 localized in many languages thanks to the awesome community
|
||||
- ➕ Many more like recipe scaling, image compression, cookbooks, printing views, ...
|
||||
|
||||
|
||||
|
||||
## Roadmap
|
||||
This application has been under rapid development over the last year.
|
||||
During this time I have learnt a lot and added tons of features, I have also moved to some new technologies like Vue.js.
|
||||
This has led to some great features but has left the Quality unsatisfactory in regard to the details and technical implementation.
|
||||
|
||||
So in addition to the new Features and Ideas which can always be found in the [Issues & Milestones](https://github.com/vabene1111/recipes/issues)
|
||||
there are some greater overall goals for the future (in no particular order)
|
||||
|
||||
- Improve the UI! The Design is inconsistent and many pages work but don't look great. This needs to change.
|
||||
- I strongly believe in Open Data and Systems. Thus adding importers and exporters for all relevant other recipe management systems is something i really want to do.
|
||||
- Move all Javascript Libraries to a packet manger and clean up some of the mess I made in the early days
|
||||
- Improve Test coverage and also the individual tests themselves
|
||||
- Improve the documentation for all features and aspects of this project and add some application integrated help
|
||||
|
||||
## About
|
||||
This application has originally been developed to index, tag and search my collection of digital (PDF) recipes.
|
||||
Over the time tons of features have been added making this the most comprehensive recipe management system.
|
||||
|
||||
I am just a single developer with many other interests and obligations so development and support might be slow at times,
|
||||
but I try my best to constantly improve this application.
|
||||
|
||||
If you have any wishes, feature requests, problems or ideas feel free to open an issue on GitHub.
|
||||
@@ -34,4 +34,5 @@ nav:
|
||||
- System:
|
||||
- Updating: system/updating.md
|
||||
- Permission System: system/permissions.md
|
||||
- Backup: system/backup.md
|
||||
- Backup: system/backup.md
|
||||
- Contributing: contribute.md
|
||||
Reference in New Issue
Block a user