From a54b6788b0aa915c3e85a00220c6a841f094a1a3 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Tue, 15 Jun 2021 15:34:29 -0700
Subject: [PATCH] Sub-headings for .transform()

---
 docs/python-api.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/python-api.rst b/docs/python-api.rst
index 45dac23..b25eb21 100644
--- a/docs/python-api.rst
+++ b/docs/python-api.rst
@@ -1071,6 +1071,9 @@ The ``table.transform()`` method can do all of these things, by implementing a m
 
 The ``.transform()`` method takes a number of parameters, all of which are optional.
 
+Altering column types
+---------------------
+
 To alter the type of a column, use the ``types=`` argument:
 
 .. code-block:: python
@@ -1080,6 +1083,9 @@ To alter the type of a column, use the ``types=`` argument:
 
 See :ref:`python_api_add_column` for a list of available types.
 
+Renaming columns
+----------------
+
 The ``rename=`` parameter can rename columns:
 
 .. code-block:: python
@@ -1087,6 +1093,9 @@ The ``rename=`` parameter can rename columns:
     # Rename 'age' to 'initial_age':
     table.transform(rename={"age": "initial_age"})
 
+Dropping columns
+----------------
+
 To drop columns, pass them in the ``drop=`` set:
 
 .. code-block:: python
@@ -1094,6 +1103,9 @@ To drop columns, pass them in the ``drop=`` set:
     # Drop the 'age' column:
     table.transform(drop={"age"})
 
+Changing primary keys
+---------------------
+
 To change the primary key for a table, use ``pk=``. This can be passed a single column for a regular primary key, or a tuple of columns to create a compound primary key. Passing ``pk=None`` will remove the primary key and convert the table into a ``rowid`` table.
 
 .. code-block:: python
@@ -1101,6 +1113,9 @@ To change the primary key for a table, use ``pk=``. This can be passed a single
     # Make `user_id` the new primary key
     table.transform(pk="user_id")
 
+Changing not null status
+------------------------
+
 You can change the ``NOT NULL`` status of columns by using ``not_null=``. You can pass this a set of columns to make those columns ``NOT NULL``:
 
 .. code-block:: python
@@ -1118,6 +1133,9 @@ If you want to take existing ``NOT NULL`` columns and change them to allow null
     # Make age allow NULL and switch weight to being NOT NULL:
     table.transform(not_null={"age": False, "weight": True})
 
+Altering column defaults
+------------------------
+
 The ``defaults=`` parameter can be used to set or change the defaults for different columns:
 
 .. code-block:: python
@@ -1128,6 +1146,9 @@ The ``defaults=`` parameter can be used to set or change the defaults for differ
     # Now remove the default from that column:
     table.transform(defaults={"age": None})
 
+Changing column order
+---------------------
+
 The ``column_order=`` parameter can be used to change the order of the columns. If you pass the names of a subset of the columns those will go first and columns you omitted will appear in their existing order after them.
 
 .. code-block:: python
@@ -1135,6 +1156,9 @@ The ``column_order=`` parameter can be used to change the order of the columns.
     # Change column order
     table.transform(column_order=("name", "age", "id")
 
+Dropping foreign key constraints
+--------------------------------
+
 You can use ``.transform()`` to remove foreign key constraints from a table.
 
 This example drops two foreign keys - the one from ``places.country`` to ``country.id`` and the one from ``places.continent`` to ``continent.id``: