Update documentation and contribution instructions

docs/src/piccolo/contributing/index.rst

@@ -37,7 +37,7 @@ Get the tests running
 * Install development dependencies: ``pip install -r requirements/dev-requirements.txt``
 * Install test dependencies: ``pip install -r requirements/test-requirements.txt``
 * Install database drivers: ``pip install -r requirements/extras/postgres.txt -r requirements/extras/sqlite.txt``
-* Setup Postgres, and make sure a database called ``piccolo`` exists (see ``tests/postgres_conf.py``).
+* Setup database engines, and make sure a database called ``piccolo`` exists (see ``tests/postgres_conf.py``, ``tests/sqlite_conf.py``, ``tests/cockroach_conf.py``). For an easy test database setup, you can use the Docker composition in ``tests/docker-compose.yml``.
 * Run the automated code linting/formatting tools: ``./scripts/lint.sh``
 * Run the test suite with Postgres: ``./scripts/test-postgres.sh``
 * Run the test suite with Cockroach: ``./scripts/test-cockroach.sh``
@@ -65,19 +65,22 @@ Piccolo uses `Black <https://black.readthedocs.io/en/stable/>`_  for
 formatting, preferably with a max line length of 79, to keep it consistent
 with `PEP8 <https://python.org/dev/peps/pep-0008/>`_ .
 
-You can configure `VSCode <https://code.visualstudio.com/>`_ by modifying
-``settings.json`` as follows:
+You can configure `VSCode <https://code.visualstudio.com/>`_ by  installing
+`MyPy <https://open-vsx.org/extension/ms-python/mypy-type-checker>`_ and
+`Black <https://open-vsx.org/extension/ms-python/black-formatter>`_ extensions
+and modifying ``settings.json`` as follows:
 
 .. code-block:: json
 
     {
-        "python.linting.enabled": true,
-        "python.linting.mypyEnabled": true,
-        "python.formatting.provider": "black",
-        "python.formatting.blackArgs": [
-            "--line-length",
-            "79"
-        ],
+        "mypy-type-checker.reportingScope": "workspace",
+        "mypy-type-checker.preferDaemon": true,
+        "mypy-type-checker.importStrategy": "fromEnvironment",
+        "black-formatter.importStrategy": "fromEnvironment",
+        "black-formatter.args": ["--line-length", "79"],
+        "[python]": {
+            "editor.defaultFormatter": "ms-python.black-formatter"
+        },
         "editor.formatOnSave": true
     }
 

docs/src/piccolo/projects_and_apps/included_apps.rst

@@ -113,7 +113,7 @@ There are two options:
 And finally, if you're loading a really large fixture, you can specify the
 ``chunk_size``. By default, Piccolo inserts up to 1,000 rows at a time, as
 the database adapter will complain if a single insert query is too large. So
-if your fixture containts 10,000 rows, this will mean 10 insert queries.
+if your fixture contains 10,000 rows, this will mean 10 insert queries.
 
 You can tune this number higher or lower if you want (lower if the
 table has a lot of columns, or higher if the table has few columns).
@@ -122,6 +122,27 @@ table has a lot of columns, or higher if the table has few columns).
 
     piccolo fixtures load fixtures.json --chunk_size=500
 
+You can have an example of the expected structure of the `fixtures.json` file by
+dumping existing data to a fixture file. If you don't have any data, here is a
+short example:
+
+.. code-block:: json
+
+    {
+        "my_wonderful_piccolo_app": {
+            "Manager": [
+                { "id": 1, "name": "Dave" },
+                { "id": 2, "name": "Pythonistas" },
+                { "id": 2, "name": "Rustaceans" }
+            ],
+            "Band": [
+                { "id": 1, "name": "Pythonistas" "manager": 2 },
+                { "id": 2, "name": "Darts", "manager": 2 },
+                { "id": 3, "name": "Gophers", "manager": 1 }
+            ]
+        }
+    }
+
 -------------------------------------------------------------------------------
 
 meta

tests/docker-compose.yaml

@@ -0,0 +1,21 @@
+services:
+  postgres:
+    image: docker.io/postgres:18-alpine
+    ports:
+      - '${PG_PORT:-5432}:5432'
+    environment:
+      POSTGRES_HOST: ${PG_HOST:-localhost}
+      POSTGRES_USER: ${PG_USER:-postgres}
+      POSTGRES_PASSWORD: ${PG_PASSWORD}
+      POSTGRES_DB: ${PG_DATABASE:-piccolo}
+      POSTGRES_HOST_AUTH_METHOD: trust
+
+  cockroach:
+    image: cockroachdb/cockroach:latest-v25.4
+    ports:
+      - '${PG_PORT:-26257}:26257'
+    environment:
+      COCKROACH_USER: ${PG_USER:-postgres}
+      COCKROACH_PASSWORD: ${PG_PASSWORD}
+      COCKROACH_DATABASE: ${PG_DATABASE:-piccolo}
+    command: start-single-node --insecure