diff --git a/.flake8 b/.flake8 new file mode 100644 index 000000000..f3353121e --- /dev/null +++ b/.flake8 @@ -0,0 +1,22 @@ +[flake8] +extend-ignore = + # Whitespace before ':' - Required for black compatibility + E203, + # Line break occurred before a binary operator - Required for black compatibility + W503, + # Comparison to False should be 'if cond is False:' or 'if not cond:' + E712 +exclude = + .git, + **/__pycache__, + **/.git, + **/.svn, + **/.hg, + **/CVS, + **/.DS_Store, + .vscode, + **/*.pyc +per-file-ignores= + cookbook/apps.py:F401 +max-line-length = 179 + diff --git a/.vscode/settings.json b/.vscode/settings.json index 1f900399c..b7c5c054b 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -3,5 +3,10 @@ "cookbook/tests" ], "python.testing.unittestEnabled": false, - "python.testing.pytestEnabled": true -} \ No newline at end of file + "python.testing.pytestEnabled": true, + "editor.formatOnSave": true, + "editor.defaultFormatter": "esbenp.prettier-vscode", + "[python]": { + "editor.defaultFormatter": "eeyore.yapf", + } +} diff --git a/docs/contribute.md b/docs/contribute.md index 545ded755..7e5c4eece 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -1,59 +1,88 @@ 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. +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 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. ## Contributing Code + 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 +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 !!! 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. +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 + +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 +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`. ### VSCode Tasks -If you use VSCode, there are a number of 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. +If you use VSCode, there are a number of 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. +- `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. + +!!! info linting and formating +This project uses black, flake8, isort, prettier, and ESLint to lint and format the code. In order to submit a PR you must use the +project standard configurations. + + ##### VSCode: + Install the official plugins: black-formatter, flake8, isort + Add the following line to your settings.json: + ``` json + "editor.formatOnSave": true, + "editor.defaultFormatter": "esbenp.prettier-vscode", + "[python]": { + "editor.defaultFormatter": "ms-python.black-formatter", + } + ``` + + ##### PyCharm + Add the following line to your settings.json: + ``` json + "[python]": { + "editor.defaultFormatter": "ms-python.flake8", + "editor.formatOnSave": true + }, + ``` ### Django -This application is developed using the Django framework for Python. They have excellent + +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. + 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`. @@ -62,15 +91,17 @@ There is **no** need to set any environment variables. By default, a simple SQLi populated from default values. ### Vue.js -Most new frontend pages are build using [Vue.js](https://vuejs.org/). + +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. +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. #### API Client + 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. @@ -81,6 +112,7 @@ 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.) ## Contribute Documentation + The documentation is built from the markdown files in the [docs](https://github.com/vabene1111/recipes/tree/develop/docs) folder of the GitHub repository. @@ -104,14 +136,14 @@ You can simply register an account and then follow these steps to add translatio 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. +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 -i venv`. Once finished, simply open a PR with the changed files. This sometimes causes issues merging +It is also possible to provide the translations directly by creating a new language +using `manage.py makemessages -l -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. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 000000000..974b61d90 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,14 @@ +[tool.yapf] +column_limit = 179 +based_on_style = "pep8" +# each_dict_entry_on_separate_line = true +DISABLE_ENDING_COMMA_HEURISTIC = false +COALESCE_BRACKETS = true +DEDENT_CLOSING_BRACKETS = true +FORCE_MULTILINE_DICT = false + +[tool.isort] +multi_line_output = 3 +include_trailing_comma = true +skip = [".gitignore", ".dockerignore"] +line_length = 179 diff --git a/requirements.txt b/requirements.txt index b457d2c46..03574e211 100644 --- a/requirements.txt +++ b/requirements.txt @@ -53,3 +53,6 @@ pytest-factoryboy==2.6.0 pytest-html==4.1.1 pytest-asyncio==0.23.5 pytest-xdist==3.5.0 +autopep8==2.0.4 +flake8==6.1.0 +yapf==0.40.2 diff --git a/vue/package.json b/vue/package.json index 02c8fe1fc..5615b558d 100644 --- a/vue/package.json +++ b/vue/package.json @@ -97,5 +97,11 @@ "resolutions": { "@vue/cli-plugin-pwa/workbox-webpack-plugin": "^5.1.3", "coa": "2.0.2" + }, + "prettier": { + "printWidth": 179, + "trailingComma": "es5", + "tabWidth": 2, + "semi": false } }