[5/n] docs: Add documentation or django-dbbackup

Message ID 20181009100300.27237-1-stephen@that.guru
State Accepted
Headers show
Series
  • [5/n] docs: Add documentation or django-dbbackup
Related show

Commit Message

Stephen Finucane Oct. 9, 2018, 10:03 a.m.
This replaces the older, manual backup steps. The section of
'django-debug-toolbar' is updated to match the new 'django-dbbackup'
section.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 docs/development/installation.rst | 72 ++++++++++++++++++++++---------
 1 file changed, 51 insertions(+), 21 deletions(-)

Patch

diff --git a/docs/development/installation.rst b/docs/development/installation.rst
index 98222694..2ad9183d 100644
--- a/docs/development/installation.rst
+++ b/docs/development/installation.rst
@@ -64,6 +64,18 @@  To access the SQL command-line client, run:
 
    $ docker-compose run --rm web python manage.py dbshell
 
+To backup the database, run:
+
+.. code-block:: shell
+
+   $ docker-compose run --rm web python manage.py dbbackup
+
+Likewise, to restore an older version of the database, run:
+
+.. code-block:: shell
+
+   $ docker-compose run --rm -web python manage.py dbrestore
+
 To run unit tests against the system Python packages, run:
 
 .. code-block:: shell
@@ -77,24 +89,11 @@  To run unit tests for multiple versions using ``tox``, run:
    $ docker-compose run --rm web tox
 
 To reset the database before any of these commands, add ``--reset`` to the
-command line after ``web`` and before any other arguments. Conversely, to
-backup the database at any stage, run:
-
-.. code-block:: shell
-
-   $ docker exec DATABASECONTAINER /usr/bin/mysqldump -u patchwork \
-       --password=password patchwork > backup.sql
-
-where ``DATABASECONTAINER`` is found by ``docker ps -a`` and the other settings
-are the same as those defined in ``patchwork/settings/dev.py``. To restore this
-again, run:
+command line after ``web`` and before any other arguments:
 
 .. code-block:: shell
 
-    $ docker-compose run --rm web python manage.py dbshell
-    mysql> use patchwork;
-    mysql> set autocommit=0; source backup.sql; commit;
-    mysql> exit;
+   $ docker-compose run --rm web --reset tox
 
 Any local edits to the project files made locally are immediately visible to
 the Docker container, and so should be picked up by the Django auto-reloader.
@@ -393,7 +392,7 @@  registered with on the Mailman instance found at ``mm_host``.
 
    We provide instructions for downloading archives from the Patchwork mailing
    list, but almost any instance of Mailman will allow downloading of archives
-   as seen above; simply change the `pw_url` variable defined. You can find
+   as seen above; simply change the ``pw_url`` variable defined. You can find
    more informations about this `here`__.
 
 Load these archives into Patchwork. Depending on the size of the downloaded
@@ -428,10 +427,41 @@  __ http://blog.behnel.de/posts/indexp118.html
 Django Debug Toolbar
 --------------------
 
-Patchwork installs and enables the 'Django Debug Toolbar' by default. However,
-by default this is only displayed if you are developing on localhost. If
-developing on a different machine, you should configure an SSH tunnel such
-that, for example, ``localhost:8000`` points to ``[DEV_MACHINE_IP]:8000``.
+Patchwork installs and enables the 'Django Debug Toolbar' application by
+default when using development settings and requirements. This provides a
+configurable set of panels that display various debug information about the
+current request/response and, when clicked, display more details about the
+panel's content.
+
+.. important::
+
+   By default, the toolbar is only displayed if you are developing on
+   localhost.  If developing on a different machine, you should configure an
+   SSH tunnel such that, for example, ``localhost:8000`` points to
+   ``[DEV_MACHINE_IP]:8000``.
+
+For more information, refer to the `documentation`__.
+
+__ https://django-debug-toolbar.readthedocs.io/en/stable/
+
+
+.. _dev-dbbackup:
+
+Django Database Backup
+----------------------
+
+Patchwork installs and enables the 'Django Database Backup' application by
+default when using development settings and requirements. This provides the
+following management commands, which can be useful for hacking on Patchwork:
+
+- ``dbbackup``
+- ``dbrestore``
+- ``mediabackup``
+- ``mediarestore``
+
+For more information, refer to the `documentation`__.
+
+__ https://django-dbbackup.readthedocs.io/en/stable/
 
 
 .. _dev-envvar:
@@ -440,7 +470,7 @@  Environment Variables
 ---------------------
 
 The following environment variables are available to configure settings when
-using the provided `dev` settings file.
+using the provided ``dev`` settings file.
 
 ``PW_TEST_DB_NAME=patchwork``
   Name of the database