From 86562a818d2e59add6b58702264a8f4761d51dee Mon Sep 17 00:00:00 2001 From: "Nikita P. Shupeyko" Date: Wed, 7 Mar 2018 14:04:24 +0300 Subject: [PATCH] Clean up the docs --- README.rst | 2 +- docs/deployment-on-pythonanywhere.rst | 2 +- docs/deployment-with-docker.rst | 14 ++--- docs/developing-locally-docker.rst | 88 ++++++++++----------------- docs/docker-postgres-backups.rst | 8 +-- docs/faq.rst | 12 ++-- docs/project-generation-options.rst | 8 +-- docs/troubleshooting.rst | 5 +- 8 files changed, 59 insertions(+), 80 deletions(-) diff --git a/README.rst b/README.rst index 3f8245f83..e2c24f5bc 100644 --- a/README.rst +++ b/README.rst @@ -129,7 +129,7 @@ Pyup brings you automated security and dependency updates used by Google and oth Usage ------ -Let's pretend you want to create a Django project called "redditclone". Rather than using `startproject` +Let's pretend you want to create a Django project called "redditclone". Rather than using ``startproject`` and then editing the results to include your name, email, and various configuration issues that always get forgotten until the worst possible moment, get cookiecutter_ to do all the work. First, get Cookiecutter. Trust me, it's awesome:: diff --git a/docs/deployment-on-pythonanywhere.rst b/docs/deployment-on-pythonanywhere.rst index 995da7b03..ea25b3ae5 100644 --- a/docs/deployment-on-pythonanywhere.rst +++ b/docs/deployment-on-pythonanywhere.rst @@ -83,7 +83,7 @@ Database setup: Go to the PythonAnywhere **Databases tab** and configure your database. -* For Postgres, setup your superuser password, then open a Postgres console and run a `CREATE DATABASE my-db-name`. You should probably also set up a specific role and permissions for your app, rather than using the superuser credentials. Make a note of the address and port of your postgres server. +* For Postgres, setup your superuser password, then open a Postgres console and run a ``CREATE DATABASE my-db-name``. You should probably also set up a specific role and permissions for your app, rather than using the superuser credentials. Make a note of the address and port of your postgres server. * For MySQL, set the password and create a database. More info here: https://help.pythonanywhere.com/pages/UsingMySQL diff --git a/docs/deployment-with-docker.rst b/docs/deployment-with-docker.rst index 25ff7cb9f..9e9d635e7 100644 --- a/docs/deployment-with-docker.rst +++ b/docs/deployment-with-docker.rst @@ -1,5 +1,5 @@ Deployment with Docker -======================= +====================== .. index:: Docker, deployment @@ -10,7 +10,7 @@ Prerequisites * Docker Compose (at least 1.6) Understand the Compose Setup --------------------------------- +---------------------------- Before you start, check out the `production.yml` file in the root of this project. This is where each component of this application gets its configuration from. Notice how it provides configuration for these services: @@ -73,12 +73,12 @@ You can read more about this here at `Automatic HTTPS`_ in the Caddy docs. .. _Automatic HTTPS: https://caddyserver.com/docs/automatic-https -Optional: Postgres Data Volume Modifications +(Optional) Postgres Data Volume Modifications --------------------------------------------- Postgres is saving its database files to the `postgres_data` volume by default. Change that if you want something else and make sure to make backups since this is not done automatically. -Run your app with docker-compose +Run your app with Docker Compose -------------------------------- To get started, pull your code from source control (don't forget the `.env` file) and change to your projects root @@ -94,15 +94,15 @@ Once this is ready, you can run it with:: To run a migration, open up a second terminal and run:: - docker-compose -f production.yml run django python manage.py migrate + docker-compose -f production.yml run --rm django python manage.py migrate To create a superuser, run:: - docker-compose -f production.yml run django python manage.py createsuperuser + docker-compose -f production.yml run --rm django python manage.py createsuperuser If you need a shell, run:: - docker-compose -f production.yml run django python manage.py shell + docker-compose -f production.yml run --rm django python manage.py shell To get an output of all running containers. diff --git a/docs/developing-locally-docker.rst b/docs/developing-locally-docker.rst index 99622c3ca..b4b1ebfd6 100644 --- a/docs/developing-locally-docker.rst +++ b/docs/developing-locally-docker.rst @@ -6,6 +6,7 @@ Getting Up and Running Locally With Docker The steps below will get you up and running with a local development environment. All of these commands assume you are in the root of your generated project. + Prerequisites ------------- @@ -21,6 +22,7 @@ If you don't already have it installed, follow the instructions for your OS: .. _`Docker for Windows`: https://docs.docker.com/engine/installation/windows/ .. _`docker-engine`: https://docs.docker.com/engine/installation/ + Attention Windows users ----------------------- @@ -31,6 +33,7 @@ Currently PostgreSQL (``psycopg2`` python package) is not installed inside Docke Doing this will prevent the project from being installed in an Windows-only environment (thus without usage of Docker). If you want to use this project without Docker, make sure to remove ``psycopg2`` from the requirements again. + Build the Stack --------------- @@ -39,10 +42,10 @@ on your development system:: $ docker-compose -f local.yml build -If you want to build the production environment you use ``production.yml`` as -f argument (``docker-compose.yml`` or ``docker-compose.yaml`` are the defaults). +Generally, if you want to emulate production environment use ``production.yml`` instead. And this is true for any other actions you might need to perform: whenever a switch is required, just do it! -Boot the System ---------------- +Run the Stack +------------- This brings up both Django and PostgreSQL. @@ -61,53 +64,44 @@ And then run:: $ docker-compose up -Running management commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To run in a detached (background) mode, just:: + + $ docker-compose up -d + + +Execute Management Commands +--------------------------- As with any shell command that we wish to run in our container, this is done -using the ``docker-compose -f local.yml run`` command. +using the ``docker-compose -f local.yml run --rm`` command. To migrate your app and to create a superuser, run:: - $ docker-compose -f local.yml run django python manage.py migrate - $ docker-compose -f local.yml run django python manage.py createsuperuser + $ docker-compose -f local.yml run --rm django python manage.py migrate + $ docker-compose -f local.yml run --rm django python manage.py createsuperuser -Here we specify the ``django`` container as the location to run our management commands. +Here, ``django`` is the target service we want to execute the commands against. -Add your Docker development server IP -------------------------------------- -When ``DEBUG`` is set to `True`, the host is validated against ``['localhost', '127.0.0.1', '[::1]']``. This is adequate when running a ``virtualenv``. For Docker, in the ``config.settings.local``, add your host development server IP to ``INTERNAL_IPS`` or ``ALLOWED_HOSTS`` if the variable exists. +(Optionally) Designate your Docker Development Server IP +-------------------------------------------------------- -Production Mode -~~~~~~~~~~~~~~~ +When ``DEBUG`` is set to ``True``, the host is validated against ``['localhost', '127.0.0.1', '[::1]']``. This is adequate when running a ``virtualenv``. For Docker, in the ``config.settings.local``, add your host development server IP to ``INTERNAL_IPS`` or ``ALLOWED_HOSTS`` if the variable exists. -Instead of using `local.yml`, you would use `production.yml`. -Other Useful Tips ------------------ +Tips & Tricks +------------- -Make a machine the active unit -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Activate a Docker Machine +~~~~~~~~~~~~~~~~~~~~~~~~~ This tells our computer that all future commands are specifically for the dev1 machine. -Using the ``eval`` command we can switch machines as needed. - -:: +Using the ``eval`` command we can switch machines as needed.:: $ eval "$(docker-machine env dev1)" -Detached Mode -~~~~~~~~~~~~~ - -If you want to run the stack in detached mode (in the background), use the ``-d`` argument: - -:: - - $ docker-compose -f local.yml up -d - Debugging -~~~~~~~~~~~~~ +~~~~~~~~~ ipdb """"" @@ -122,37 +116,21 @@ Then you may need to run the following for it to work as desired: :: - $ docker-compose -f local.yml run --service-ports django + $ docker-compose -f local.yml run --rm --service-ports django django-debug-toolbar """""""""""""""""""" -In order for django-debug-toolbar to work with docker you need to add your docker-machine ip address to ``INTERNAL_IPS`` in ``local.py`` +In order for ``django-debug-toolbar`` to work designate your Docker Machine IP with ``INTERNAL_IPS`` in ``local.py``. -.. May be a better place to put this, as it is not Docker specific. +Mailhog +~~~~~~~ -You may need to add the following to your css in order for the django-debug-toolbar to be visible (this applies whether Docker is being used or not): +When developing locally you can go with MailHog_ for email testing provided ``use_mailhog`` was set to ``y`` on setup. To proceed, -.. code-block:: css - - /* Override Bootstrap 4 styling on Django Debug Toolbar */ - #djDebug[hidden], #djDebug [hidden] { - display: block !important; - } - - #djDebug [hidden][style='display: none;'] { - display: none !important; - } - - -Using the Mailhog Docker Container -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In development you can (optionally) use MailHog_ for email testing. If you selected `use_docker`, MailHog is added as a Docker container. To use MailHog: - -1. Make sure, that ``mailhog`` docker container is up and running -2. Open your browser and go to ``http://127.0.0.1:8025`` +1. make sure ``mailhog`` container is up and running; +1. open up ``http://127.0.0.1:8025``. .. _Mailhog: https://github.com/mailhog/MailHog/ diff --git a/docs/docker-postgres-backups.rst b/docs/docker-postgres-backups.rst index d3c7ca1d4..d0ad1a52d 100644 --- a/docs/docker-postgres-backups.rst +++ b/docs/docker-postgres-backups.rst @@ -2,7 +2,7 @@ Database Backups with Docker ============================ -The database has to be running to create/restore a backup. These examples show local examples. If you want to use it on a remote server, remove ``-f local.yml`` from each example. +The database has to be running to create/restore a backup. These examples show local examples. If you want to use it on a remote server, use ``-f production.yml`` instead. Running Backups ================ @@ -11,17 +11,17 @@ Run the app with `docker-compose -f local.yml up`. To create a backup, run:: - docker-compose -f local.yml run postgres backup + docker-compose -f local.yml run --rm postgres backup To list backups, run:: - docker-compose -f local.yml run postgres list-backups + docker-compose -f local.yml run --rm postgres list-backups To restore a backup, run:: - docker-compose -f local.yml run postgres restore filename.sql + docker-compose -f local.yml run --rm postgres restore filename.sql Where is the ID of the Postgres container. To get it, run:: diff --git a/docs/faq.rst b/docs/faq.rst index def4ba1f9..1481a8bac 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -1,5 +1,5 @@ FAQ -==== +=== .. index:: FAQ, 12-Factor App @@ -17,11 +17,11 @@ Why aren't you using just one configuration file (12-Factor App) ---------------------------------------------------------------------- TODO +.. TODO -Why doesn't this follow the layout from Two Scoops of Django 1.8? ----------------------------------------------------------------------- +Why doesn't this follow the layout from Two Scoops of Django? +------------------------------------------------------------- -You may notice that some elements of this project do not exactly match what we describe in chapter 3 of `Two Scoops of Django`_. The reason for that is this project, amongst other things, serves as a test bed for trying out new ideas and concepts. Sometimes they work, sometimes they don't, but the end result is that it won't necessarily match precisely what is described in the book I co-authored. +You may notice that some elements of this project do not exactly match what we describe in chapter 3 of `Two Scoops of Django 1.11`_. The reason for that is this project, amongst other things, serves as a test bed for trying out new ideas and concepts. Sometimes they work, sometimes they don't, but the end result is that it won't necessarily match precisely what is described in the book I co-authored. - -.. _`Two Scoops of Django`: http://twoscoopspress.com/products/two-scoops-of-django-1-8 +.. _Two Scoops of Django 1.11: https://www.twoscoopspress.com/collections/django/products/two-scoops-of-django-1-11 diff --git a/docs/project-generation-options.rst b/docs/project-generation-options.rst index 9e09f0e5d..2ca2872ce 100644 --- a/docs/project-generation-options.rst +++ b/docs/project-generation-options.rst @@ -10,10 +10,10 @@ project_slug [my_awesome_project]: is needed. description [Behold My Awesome Project!] - Describes your project and gets used in places like `README.rst` and such. + Describes your project and gets used in places like ``README.rst`` and such. author_name [Daniel Roy Greenfeld]: - This is you! The value goes into places like `LICENSE` and such. + This is you! The value goes into places like ``LICENSE`` and such. email [daniel-roy-greenfeld@example.com]: The email address you want to identify yourself in the project. @@ -35,7 +35,7 @@ open_source_license [1] 5. Not open source timezone [UTC] - The value to be used for the `TIME_ZONE` setting of the project. + The value to be used for the ``TIME_ZONE`` setting of the project. windows [n] Indicates whether the project should be configured for development on Windows. @@ -95,7 +95,7 @@ use_travisci [n] Indicates whether the project should be configured to use `Travis CI`_. keep_local_envs_in_vcs [y] - Indicates whether the project's `.envs/.local/` should be kept in VCS + Indicates whether the project's ``.envs/.local/`` should be kept in VCS (comes in handy when working in teams where local environment reproducibility is strongly encouraged). diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index fe121b9cd..4a682ac20 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -3,7 +3,8 @@ Troubleshooting This page contains some advice about errors and problems commonly encountered during the development of Cookiecutter Django applications. -#. If you get the error ``jinja2.exceptions.TemplateSyntaxError: Encountered unknown tag 'now'.`` , please upgrade your cookiecutter version to >= 1.4 (see issue # 528_ ) #. ``project_slug`` must be a valid Python module name or you will have issues on imports. -.. _528: https://github.com/pydanny/cookiecutter-django/issues/528#issuecomment-212650373 \ No newline at end of file +#. ``jinja2.exceptions.TemplateSyntaxError: Encountered unknown tag 'now'.``: please upgrade your cookiecutter version to >= 1.4 (see # 528_) + +.. _528: https://github.com/pydanny/cookiecutter-django/issues/528#issuecomment-212650373