Merge pull request #316 from KyleWJohnston/develop

Improve documentation formatting

README.md

@@ -4,8 +4,8 @@
 ![Forks](https://img.shields.io/github/forks/vabene1111/recipes)
 ![Docker Pulls](https://img.shields.io/docker/pulls/vabene1111/recipes)
 
-Recipes is a Django application to manage, tag and search recipes using either built in models or 
+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.
+external storage providers hosting PDF's, images or other files.
 
 ![Preview](docs/preview.png)
 
@@ -14,27 +14,27 @@ external storage providers hosting PDF's, Images or other files.
 ## Features
 
 - :package: **Sync** files with Dropbox and Nextcloud (more can easily be added)
-- :mag: Powerful **search** with Djangos [TrigramSimilarity](https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/search/#trigram-similarity)
+- :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
+- :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
+- :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
+- :earth_africa: Localized in many languages thanks to the awesome community
 - :heavy_plus_sign: 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 
 a public page.
-Some Documentation can be found [here](https://github.com/vabene1111/recipes/wiki)
+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
+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
@@ -44,18 +44,18 @@ Please refer to the Installation section of the [Documentation](https://vabene11
 
 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.**
+**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 
+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
+[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.
+    1. If you want, create a virutal environment for all your packages.
-3. Install all required packages by running `pip install -r requirements.txt`
+3. Install all required packages: `pip install -r requirements.txt`
-4. Run the migrations `python manage.py migrate`
+4. Run the migrations: `python manage.py migrate`
-5. Start the development server `python manage.py runserver`
+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.
@@ -64,7 +64,7 @@ populated from default values.
 
 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. 
+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. 
 
 ## License
 

docs/install/docker.md

@@ -2,28 +2,29 @@
     Setting up this application using Docker is recommended. This does not mean that other options are bad, just that
     support is much easier for this setup.
 
-It is possible to install this application using many docker configurations.
+It is possible to install this application using many Docker configurations.
 
 Please read the instructions/notes on each example carefully and decide if this is the way for you.
 
 ## Docker
 
-The docker image (`vabene1111/recipes`) simply exposes the application on port `8080`.
+The docker image (`vabene1111/recipes`) simply exposes the application on the container's port `8080`.
 
-It can be run using
+It can be run and accessed on port 80 using:
 
 ```shell
 docker run -d \
     -v ./staticfiles:/opt/recipes/staticfiles \
     -v ./mediafiles:/opt/recipes/mediafiles \
     -p 80:8080 \
-    -e SECRET_KEY=
+    -e SECRET_KEY=YOUR_SECRET_KEY \
-    -e DB_ENGINE=django.db.backends.postgresql
+    -e DB_ENGINE=django.db.backends.postgresql \
-    -e POSTGRES_HOST=db_recipes
+    -e POSTGRES_HOST=db_recipes \
-    -e POSTGRES_PORT=5432
+    -e POSTGRES_PORT=5432 \
-    -e POSTGRES_USER=djangodb
+    -e POSTGRES_USER=djangodb \
-    -e POSTGRES_PASSWORD=
+    -e POSTGRES_PASSWORD=YOUR_POSTGRES_SECRET_KEY \
-    -e POSTGRES_DB=djangodb
+    -e POSTGRES_DB=djangodb \
+    --name recipes_1 \
     vabene1111/recipes
 ```
 
@@ -33,18 +34,18 @@ file in the GitHub repository to verify if additional environment variables are
 
 ## Docker Compose
 
-The main and also recommended installation option is to install this application using docker compose.
+The main, and also recommended, installation option is to install this application using Docker Compose.
 
-1. Choose your `docker-compose.yml` from the examples below
+1. Choose your `docker-compose.yml` from the examples below.
-2. Download the `.env` configuration file and **edit it accordingly**.
+2. Download the `.env` configuration file with `wget`, then **edit it accordingly**.
    ```shell
    wget https://raw.githubusercontent.com/vabene1111/recipes/develop/.env.template -O .env
    ```
-3. Start your container using `docker-compose up -d`
+3. Start your container using `docker-compose up -d`.
 
 ### Plain
 
-This configuration exposes the application trough a nginx web server on port 80 of you machine.
+This configuration exposes the application through an nginx web server on port 80 of your machine.
 
 ```yaml
 version: "3"
@@ -82,8 +83,8 @@ services:
       - mediafiles:/media
 
 volumes:
-  nginx
+  nginx_config:
-  staticfiles
+  staticfiles:
   mediafiles:
     driver: local
     driver_opts:
@@ -97,11 +98,11 @@ volumes:
 Most deployments will likely use a reverse proxy.
 
 #### Traefik
-If you use traefik this configuration is the one for you.
+If you use traefik, this configuration is the one for you.
 
 !!! info
     Traefik can be a little confusing to setup.
-    Please refer to [their excellent documentation](https://doc.traefik.io/traefik/). If that does not help
+    Please refer to [their excellent documentation](https://doc.traefik.io/traefik/). If that does not help,
     [this little example](traefik.md) might be for you.
 
 ```yaml
@@ -167,7 +168,7 @@ volumes:
 
 #### nginx-proxy
 
-This is a docker compose example when using [jwilder's nginx reverse proxy](https://github.com/jwilder/docker-gen) 
+This is a docker compose example using [jwilder's nginx reverse proxy](https://github.com/jwilder/docker-gen)
 in combination with [jrcs's letsencrypt companion](https://hub.docker.com/r/jrcs/letsencrypt-nginx-proxy-companion/).
 
 Please refer to the appropriate documentation on how to setup the reverse proxy and networks.
@@ -243,17 +244,17 @@ All examples use an additional `nginx` container to serve mediafiles and act as
 This is **technically not required** but **very much recommended**.
 
 I do not 100% understand the deep technical details but the [developers of gunicorn](https://serverfault.com/questions/331256/why-do-i-need-nginx-and-something-like-gunicorn/331263#331263),
-the WSGi server that handles the python execution, explicitly state that it is not recommended to deploy without nginx.
+the WSGi server that handles the Python execution, explicitly state that it is not recommended to deploy without nginx.
 You will also likely not see any decrease in performance or a lot of space used as nginx is a very light container.
 
 !!! info
     Even if you run behind a reverse proxy as described above, using an additional nginx container is the recommended option.
 
-If you run a small private deployment and dont care about performance, security and whatever else feel free to run 
+If you run a small private deployment and don't care about performance, security and whatever else feel free to run
 without a ngix container.
 
 !!! warning
-    When running without nginx make sure to enable `GUNICORN_MEDIA` in the `.env`. Without it media files will be uploaded
+    When running without nginx make sure to enable `GUNICORN_MEDIA` in the `.env`. Without it, media files will be uploaded
     but not shown on the page.
 
 For additional information please refer to the [0.9.0 Release](https://github.com/vabene1111/recipes/releases?after=0.9.0)
@@ -263,38 +264,38 @@ See also refer to the [official gunicorn docs](https://docs.gunicorn.org/en/stab
 ### Nginx Config
 
 In order to give the user (you) the greatest amount of freedom when choosing how to deploy this application the
-webserver is not directly bundled with the docker image.
+webserver is not directly bundled with the Docker image.
 
 This has the downside that it is difficult to supply the configuration to the webserver (e.g. nginx). Up until
-Version `0.13.0` this had to be done manually by downloading the nginx config file and placing it in a directory that
+version `0.13.0`, this had to be done manually by downloading the nginx config file and placing it in a directory that
 was then mounted into the nginx container.
 
-From version `0.13.0` the config file is supplied using the application image (`vabene1111/recipes`). It is then mounted
+From version `0.13.0`, the config file is supplied using the application image (`vabene1111/recipes`). It is then mounted
 to the host system and from there into the nginx container.
 
 This is not really a clean solution, but I could not find any better alternative that provided the same amount of
-usability. If you know of any better way feel free to open an issue.
+usability. If you know of any better way, feel free to open an issue.
 
 ### Using Proxy Authentication
 
 !!! Info "Community Contributed Tutorial"
-     This tutorial was provided by a community member. Since i do not use reverse proxy authentication i cannot provide any
+     This tutorial was provided by a community member. Since I do not use reverse proxy authentication, I cannot provide any
      assistance should you choose to use this authentication method.
 
 In order use proxy authentication you will need to:
 
-1. set `REVERSE_PROXY_AUTH=1` in the `.env` file
+1. Set `REVERSE_PROXY_AUTH=1` in the `.env` file
-2. update your nginx configuration file
+2. Update your nginx configuration file
 
 Using any of the examples above will automatically generate a configuration file inside a docker volume.
 Use `docker volume inspect recipes_nginx` to find out where your volume is stored.
 
 !!! warning "Configuration File Volume"
     The nginx config volume is generated when the container is first run. You can change the volume to a bind mount in the
-    warning `docker-compose.yml` but then you will need to manually create it. See Section `Volumes vs Bind Mounts` below
+    warning `docker-compose.yml`, but then you will need to manually create it. See section `Volumes vs Bind Mounts` below
     for more information.
 
-The following example shows a configuration for Authelia
+The following example shows a configuration for Authelia:
 
 ```
 server {
@@ -338,10 +339,10 @@ server {
 
 Please refer to the appropriate documentation on how to setup the reverse proxy, authentication, and networks.
 
-Ensure users have been configured for Authelia, and that the endpoint that recipes is pointed to is protected, but
+Ensure users have been configured for Authelia, and that the endpoint recipes is pointed to is protected but
 available.
 
-There is a good guide to the other additional files that need to be added to your Nginx set up at
+There is a good guide to the other additional files that need to be added to your nginx set up at
 the [Authelia Docs](https://docs.authelia.com/deployment/supported-proxies/nginx.html).
 
 Remember to add the appropriate environment variables to `.env` file (example for nginx proxy):