Merge pull request #15 from kraken-tech/docs-tweaks-20240815

Docs tweaks 20240815

README.md

@@ -1,9 +1,7 @@
 # Django Postgres Migration Tools
 
-Django Postgres Migration Tools provides extra functionalities to make Django
-migrations safer and more scalable.
+Tools to make Django migrations safer and more scalable.
 
 ## Documentation
 
-For a full view of the latest documentation, please refer to
-[https://django-pg-migration-tools.readthedocs.io/en/latest/](https://django-pg-migration-tools.readthedocs.io/en/latest/)
+[Full documentation](https://django-pg-migration-tools.readthedocs.io/en/latest/).

docs/index.rst

@@ -1,14 +1,15 @@
-Django Postgres Migration Tools Documentation
-=============================================
+Django Postgres Migration Tools
+===============================
 
-Django Postgres Migration Tools provides extra functionalities to make Django
-migrations safer and more scalable.
+.. image:: https://img.shields.io/pypi/v/django-pg-migration-tools.svg
+    :target: https://pypi.org/project/django-pg-migration-tools
 
-This package supports:
+.. image:: https://img.shields.io/pypi/pyversions/django-pg-migration-tools.svg
+    :alt: Python versions
+    :target: https://pypi.org/project/django-pg-migration-tools/
 
-- Python 3.10
-- Python 3.11
-- Python 3.12
+Django Postgres Migration Tools provides extra functionalities to make Django
+migrations safer and more scalable.
 
 Installation
 ============
@@ -19,7 +20,7 @@ Install from pypi::
 
 .. toctree::
    :maxdepth: 3
-   :caption: Contents:
+   :caption: Contents
 
    usage/timeouts
    usage/operations

docs/usage/management_commands.rst

@@ -4,6 +4,8 @@ Management Commands
 migrate_with_timeouts
 ---------------------
 
+Runs database migrations with timeouts.
+
 This command wraps the :ref:`apply_timeouts() <apply_timeouts>` around
 Django's ``migrate`` command, exposing two extra arguments:
 
@@ -17,12 +19,11 @@ Django's ``migrate`` command, exposing two extra arguments:
 These arguments will set the value of Postgres' ``lock_timeout`` and
 ``statement_timeout`` for the duration of the migration.
 
-====================
-Example: Basic usage
-====================
+==========
+How to use
+==========
 
-Firstly, make sure to include ``django_pg_migration_tools`` in your
-``INSTALLED_APPS``.
+1. Include ``django_pg_migration_tools`` in your ``INSTALLED_APPS``.
 
 .. code-block:: python
 
@@ -32,7 +33,7 @@ Firstly, make sure to include ``django_pg_migration_tools`` in your
         ...
     ]
 
-Now you are all set to run the management command:
+2. Run the management command:
 
 .. code-block:: bash
 

docs/usage/operations.rst

@@ -1,8 +1,7 @@
 Operations
 ==========
 
-The `operations` module provides custom migration operations that help
-developers perform idempotent and safe schema changes.
+Provides custom migration operations that help developers perform idempotent and safe schema changes.
 
 Class Definitions
 -----------------
@@ -69,8 +68,8 @@ Class Definitions
       -- Reset lock_timeout to its original value ("1s" as an example).
       SET lock_timeout = '1s';
 
-    Example 1: Basic Usage of ``SaferAddIndexConcurrently``
-    -------------------------------------------------------
+    How to use
+    ----------
 
     1. Add the index to the relevant model:
 
@@ -83,13 +82,13 @@ Class Definitions
                   # existing index
                   models.Index(fields=["bar"], name="bar_idx"),
 
-    Make the new migration
+    2. Make the new migration:
 
     .. code-block:: bash
 
       ./manage.py makemigrations
 
-    Swap the AddIndex class for our own SaferAddIndexConcurrently class.
+    3. Swap the ``AddIndex`` class for our own ``SaferAddIndexConcurrently`` class.
     Remember to use a non-atomic migration.
 
     .. code-block:: diff

docs/usage/timeouts.rst

@@ -1,7 +1,7 @@
 Timeouts
 ========
 
-The ``timeouts`` facility provides users with the ability to set Postgres
+Provides the ability to set Postgres
 `lock_timeout
 <http://web.archive.org/web/20240607131902/https://www.postgresql.org/docs/16/runtime-config-client.html#GUC-LOCK-TIMEOUT>`_
 and `statement_timeout
@@ -12,14 +12,10 @@ values.
 
   **Why use database timeouts?**
 
-  Queries that change the database schema can get blocked because of
-  long-running transactions and queries. These blocked migration queries, in
-  turn, block subsequent queries as well. This is the basic ingredient for an
-  outage.
+  Timeouts are a way of preventing queries / transactions running for too long.
 
-  Using responsible values of ``lock_timeout`` and ``statement_timeout`` in
-  places where you might have a long-running transaction or query will help
-  preventing this type of situation in the first place.
+  Why are long-running queries a problem? It's because they can block queries that change the database schema.
+  These blocked migration queries, in turn, block subsequent queries as well, potentially causing an outage.
 
 Function Definitions
 --------------------
@@ -59,14 +55,8 @@ Function Definitions
    :return: yields the result.
    :rtype: Iterator[None]
 
-Example Usage
--------------
-
-Here are some examples of how to use the ``apply_sync`` function.
-
-======================
-Example 1: Basic Usage
-======================
+Example
+-------
 
 .. code-block:: python
 
@@ -83,53 +73,8 @@ Example 1: Basic Usage
            using="default",
            lock_timeout=datetime.timedelta(seconds=5),
        ):
-           # Code inside this block will have a lock timeout of 5s
+           # Code inside this block will have a lock timeout of 5s.
            ...
 
        # We are back to the parent block, so lock timeout is 10s again.
        ...
-
-=====================================================
-Example 2: Invalid Parameters: Missing timeout values
-=====================================================
-
-.. code-block:: python
-
-   import datetime
-   from django_pg_migration_tools import timeouts
-
-   with timeouts.apply_timeouts(
-       using="default",
-   ):
-     pass
-
-**Output:**
-
-.. code-block:: text
-
-   django_pg_migration_tools.timeouts.TimeoutNotProvided: Caller must set at least one of `lock_timeout` or `statement_timeout`.
-
-
-=============================================================
-Example 3: Invalid Parameters: Negative timeout not permitted
-=============================================================
-
-.. code-block:: python
-
-   import datetime
-   from django_pg_migration_tools import timeouts
-
-   with timeouts.apply_timeouts(
-       using="default",
-       lock_timeout=datetime.timedelta(seconds=-5),
-       # Either lock_timeout or statement_timeout negative.
-       # The following would've raised an error as well.
-       # statement_timeout=datetime.timedelta(seconds=-5),
-   ):
-     pass
-
-**Output:**
-
-.. code-block:: text
-
-   django_pg_migration_tools.timeouts.TimeoutWasNotPositive: Timeouts must be greater than zero.