document configurations required for formatting and linting

docs/contribute/contribute.md

@@ -0,0 +1,55 @@
+If you like this application and want it to give back, there are many ways to contribute.
+
+!!! 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.
+
+## Translations
+
+If you know any foreign languages you can:
+Improve the translations for any of the existing languages.
+
+Add a new language to the long list of existing translations.
+
+-   Armenian
+-   Bulgarian
+-   Catalan
+-   Czech
+-   Danish
+-   Dutch
+-   English
+-   French
+-   German
+-   Hungarian
+-   Italian
+-   Latvian
+-   Norwegian
+-   Polish
+-   Russian
+-   Spanish
+-   Swedish
+
+See [here](/contribute/translations) for further information on how to contribute translation to Tandoor.
+
+## Issues and Feature Requests
+
+The most basic but also very important way of contributing is reporting issues and commenting on ideas and feature requests
+over at [GitHub issues](https://github.com/vabene1111/recipes/issues).
+
+Without feedback improvement can't happen, so don't hesitate to say what you want to say.
+
+## Documentation
+
+Helping improve the documentation for Tandoor is one of the easiest ways to give back and doesn't even require deep technical knowledge.
+You can write guides on how to install and configure Tandoor expanding our repository of non-standard configuations.
+Or you can write how-to guides using some of Tandoor's advanced features such as authentication or automation.
+
+See [here](/contribute/documentation) for more information on how to add documentation to Tandoor.
+
+## Contributing Code
+
+For the truly ambitious, you can help write code to fix issues, add additional features, or write your own scripts using
+Tandoor's extensive API and share your work with the community.
+
+Before writing any code, please make sure that you review [contribution guidelines](/contribute/guidelines) and
+[VSCode](/contribute/vscode) or [PyCharm](/contribute/pycharm) specific configurations.

docs/contribute/documentation.md

@@ -0,0 +1,26 @@
+The documentation is built from the markdown files in the [docs](https://github.com/vabene1111/recipes/tree/develop/docs)
+folder of the GitHub repository.
+
+In order to contribute to the documentation, there are a couple of methods that you can use.
+
+## Directly on GitHub
+
+You can fork the develop repository and edit the markdown files directly on the GitHub website.
+
+## With an IDE
+
+You can fork the develop repository and edit the markdown files from your favorite IDE such as VSCode or PyCharm.
+One advantage of using as IDE is that you can preview your changes by:
+
+### Installing mkdocs
+
+Now install mkdocs and dependencies: `pip install mkdocs-material mkdocs-include-markdown-plugin`.
+
+### Serving Documetation
+
+If you want to test the documentation, locally run `mkdocs serve` from the project root.
+
+## Super Low Tech
+
+Create your documentation in any work processor (or even create a video!) and [open a feature request](https://github.com/vabene1111/recipes/issues)
+attaching your document and requesting that someone add the documentation to Tandoor.

docs/contribute/guidelines.md

@@ -0,0 +1,63 @@
+If you want to contribute bug fixes or small tweaks then your pull requests are always welcome!
+
+!!! danger "Discuss First!"
+If you want to contribute larger features that introduce more complexity to the project please
+make sure to **first submit a technical description** outlining what and how you want to do it.
+This allows me and the community to give feedback and manage the complexity of the overall
+application. If you don't do this please don't be mad if I reject your PR.
+
+## License
+
+Contributing to Tandoor requires signing a Contributor License Agreement. You can review the CLA [here](https://cla-assistant.io/TandoorRecipes/recipes).
+
+## Linting & Formatting
+
+Tandoor uses a number of libraries to maintain style and formatting consistency.
+To contribute to the project you are required to use the following packages with the project defined configurations:
+
+- flake8
+- yapf
+- isort
+- prettier
+
+!!! tip "Manual Formatting"
+    It is possible to run formatting manually, but it is recommended to setup your IDE to format on save.
+    ``` bash
+    flake8 file.py --ignore=E501 | isort -q file.py | yapf -i file.py
+    prettier --write file.vue
+    ```
+
+## Testing
+Django uses pytest-django to implement a full suite of testing.  If you make any functional changes, please implment the appropriate
+tests.
+
+Tandoor is also actively soliciting contribors willing to setup vue3 testing.  If you have knowledge in this area it would be greatly appreciated.
+
+## API Client
+
+Tandoor uses [django-rest-framework](https://www.django-rest-framework.org/) for API implementation.  Making contributions that impact the API requires an understanding of
+Viewsets and Serializers.  
+
+Also double check that your changes are actively reflected in the schema so that client apis are generated accurately.
+
+The API Client is generated automatically from the OpenAPI interface provided by the Django REST framework.
+For this [openapi-generator](https://github.com/OpenAPITools/openapi-generator) is used.
+
+Install it using your desired setup method. (For example, using `npm install @openapitools/openapi-generator-cli -g`.)
+
+### Vue
+
+Navigate to `vue/src/utils/openapi`.
+
+Generate the schema using `openapi-generator-cli generate -g typescript-axios -i http://127.0.0.1:8000/openapi/`. (Replace your dev server url if required.)
+
+### Vue3
+
+Navigate to `vue3/src/openapi`.
+
+Generate the schema using `openapi-generator-cli generate -g typescript-fetch -i http://127.0.0.1:8000/openapi/`. (Replace your dev server url if required.)
+
+## Install and Configuration
+
+Instructions for [VSCode](/contribute/vscode)
+Instructions for [PyCharm](/contribute/pycharm)

docs/contribute/installation.md

@@ -0,0 +1,39 @@
+!!! info
+The dev setup is a little messy as this application combines the best (at least in my opinion) of both Django and Vue.js.
+
+### Devcontainer Setup
+
+There is a [devcontainer](https://containers.dev) set up to ease development. It is optimized for VSCode, but should be able to
+be used by other editors as well. Once the container is running, you can do things like start a Django dev server, start a Vue.js
+dev server, run python tests, etc. by either using the VSCode tasks below, or manually running commands described in the individual
+technology sections below.
+
+In VSCode, simply check out the git repository, and then via the command palette, choose `Dev Containers: Reopen in container`.
+
+If you need to change python dependencies (requierments.txt) or OS packages, you will need to rebuild the container. If you are
+changing OS package requirements, you will need to update both the main `Dockerfile` and the `.devcontainer/Dockerfile`.
+
+### Django
+
+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 (I recommend using version 3.10 or above).
+2. Open it in your favorite editor/IDE (e.g. PyCharm).
+   a. If you want, create a virtual 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.
+
+### Vue.js
+
+Most new frontend pages are build using [Vue.js](https://vuejs.org/).
+
+In order to work on these pages, you will have to install a Javascript package manager of your choice. The following examples use yarn.
+
+In the `vue` folder run `yarn install` to install the dependencies. After that you can use `yarn serve` to start the development server,
+and proceed to test your changes. If you do not wish to work on those pages, but instead want the application to work properly during
+development, run `yarn build` to build the frontend pages once.

docs/contribute/pycharm.md

@@ -0,0 +1,62 @@
+PyCharm can be configured to format and lint on save. Doing so requires some manual configuration as outlined below.
+
+## Setup File Watchers
+
+1. Navigate to File -> Settings -> Plugins
+2. Download and install [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers)
+3. Navigate to File -> Settings -> Tools -> Black
+4. Confirm 'Use Black Formatter' is unchecked for both 'On code reformat' and 'On save'
+
+## Setup flake8 Watcher
+
+1. Navigate to File -> Settings -> Tools -> File Watchers
+2. Click the '+' to add a new watcher.
+3. Configure the watcher as below.
+
+    ![flake8_watcher](assets/flake8_watcher.png)
+
+4. Navigate to File -> Settings -> Editor -> Inspections -> File watcher problems
+5. Under Severity select 'Edit Severities'
+6. Click the '+' to add a severity calling it 'Linting Error'
+7. Configure a background and effect as below.
+
+    ![linting error](assets/linting_error.png)
+
+## Setup isort
+
+1. Navigate to File -> Settings -> Tools -> File Watchers
+2. Click the '+' to add a new watcher.
+3. Configure the watcher as below.
+
+    ![yapf_watcher](assets/isort_watcher.png)
+
+## Setup yapf
+
+1. Navigate to File -> Settings -> Tools -> File Watchers
+2. Click the '+' to add a new watcher.
+3. Configure the watcher as below.
+
+    ![yapf_watcher](assets/yapf_watcher.png)
+
+<!-- prettier-ignore -->
+!!! hint
+    Adding a comma at the end of a list will trigger yapf to put each element of the list on a new line
+
+## Setup prettier
+
+1. Navigate to File -> Settings -> Tools -> File Watchers
+2. Click the '+' to add a new watcher.
+3. Change 'File Type' to 'Any'.
+4. Click the three dots next to 'Scope' to create a custom scope.
+5. Click '+' to add a new scope
+
+-   Name: prettier
+-   Pattern: `file:vue/src//*||file:vue3/src//*||file:docs//*`
+
+6. Configure the watcher as below.
+
+    ![perttier_watcher](assets/prettier_watcher.png)
+
+-   Arguments: `--cwd $ProjectFileDir$\vue prettier -w --config $ProjectFileDir$\.prettierrc $FilePath$`
+
+## Setup Volar??

docs/contribute/related.md

@@ -0,0 +1,25 @@
+## Recipe Scraper
+
+While not directly related to Tandoor, we make extensive use of the brilliant [recipe-scrapers](https://github.com/hhursev/recipe-scrapers)
+package by hhursev.
+
+If you have the skills to add new sites or help resolve issues you are indirectly helping Tandoor.
+
+## Unofficial mobile app
+
+Maintained by [phantomate](https://github.com/phantomate/Untare)
+
+[iPhone](https://apps.apple.com/nl/app/untare/id6448643329?l=en&platform=iphone)
+[Android](https://play.google.com/store/apps/details?id=unofficial.tandoor.recipes)
+
+## GPT Recipe
+
+Maintained by [John Pedrie](https://github.com/jdpedrie/gpt-recipe)
+
+Convert pictures of recipes to a structure that can be imported to Tandoor with ChatGPT.
+
+## Tandoor Menu Generator
+
+Maintained by [smilerz](https://github.com/smilerz/tandoor-menu-generator)
+
+Generate a mealplan tbased on complex criteria and optionally insert it into an SVG menu template.

docs/contribute/translations.md

@@ -0,0 +1,21 @@
+Translations are managed on [translate.tandoor.dev](https://translate.tandoor.dev/), a self hosted instance of [Weblate](https://weblate.org/de/).
+
+You can simply register an account and then follow these steps to add translations:
+
+1. After registering, you are asked to select your languages. This is optional but allows weblate to only show you relevant translations.
+2. In the navigation click on `Projects` and then `Browse all projects`.
+3. Select Tandoor and on the top-right hand corner, select `Watch project Tandoor` (click on `Not watching`).
+4. Go back to the dashboard. It now shows you the relevant translations for your languages. Click on the pencil icon to get started.
+
+!!! info "Creating a new language"
+To create a new language you must first select Tandoor (the project) and then a component.
+Here you will have the option to add the language. Afterwards you can also simply add it to the other components as well.
+Once a new language is (partially) finished let me know on GitHub so I can add it to the language-switcher in Tandoor itself.
+
+There is also [a lot of documentation](https://docs.weblate.org/en/latest/user/translating.html) available from Weblate directly.
+
+![2021-04-11_16-03](https://user-images.githubusercontent.com/6819595/114307359-926e0380-9adf-11eb-9a2b-febba56e4d8c.gif)
+
+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. This sometimes causes issues merging
+with weblate, so I would prefer the use of weblate.

docs/contribute/vscode.md

@@ -0,0 +1,45 @@
+Configurations for debugging django, volar, testing, linting and formatting are all include in the project files.
+
+## Extensions
+
+VSCode can be configured to format and lint on save instead of manually formatting files before submitting a pull request.
+To enable auto-formatting and linting install the following extensions in VSCode:
+
+Name: Flake8
+Publisher: Microsoft
+VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=ms-python.flake8
+
+Name: yapf
+Publisher: EeyoreLee
+VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=eeyore.yapf
+
+Name: isort
+Publisher: Microsoft
+VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=ms-python.isort
+
+Name: Vue - Official
+Publisher: Vue
+VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=Vue.volar
+
+Name: Prettier - Code formatter
+Publisher: Prettier
+VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
+
+<!-- prettier-ignore -->
+!!! hint
+    Adding a comma at the end of a list will trigger yapf to put each element of the list on a new line
+
+## VSCode Tasks
+
+There are a number of built in tasks that are available. Here are a few of the key ones:
+
+-   `Setup Dev Server` - Runs all the prerequisite steps so that the dev server can be run inside VSCode.
+-   `Setup Tests` - Runs all prerequisites so tests can be run inside VSCode.
+
+Once these are run, you should be able to run/debug a django server in VSCode as well as run/debug tests directly through VSCode.
+There are also a few other tasks specified in case you have specific development needs:
+
+-   `Run Dev Server` - Runs a django development server not connected to VSCode.
+-   `Run all pytests` - Runs all the pytests outside of VSCode.
+-   `Yarn Serve` - Runs development Vue.js server not connected to VSCode. Useful if you want to make Vue changes and see them in realtime.
+-   `Serve Documentation` - Runs a documentation server. Useful if you want to see how changes to documentation show up.