From 99a7906fd93ce1c6400733b855255ed62e3e9fa1 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Sat, 2 May 2020 21:13:49 -0700
Subject: [PATCH] sqlite-utils create-table docs, plus doc unit test

Refs #27. Closes #108
---
 docs/cli.rst       | 14 ++++++++++++++
 tests/test_docs.py | 22 ++++++++++++++++++++++
 2 files changed, 36 insertions(+)
 create mode 100644 tests/test_docs.py

diff --git a/docs/cli.rst b/docs/cli.rst
index ef218a0..cd5b6fd 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -334,6 +334,20 @@ The command will fail if you reference columns that do not exist on the table. T
 .. note::
     ``upsert`` in sqlite-utils 1.x worked like ``insert ... --replace`` does in 2.x. See `issue #66 <https://github.com/simonw/sqlite-utils/issues/66>`__ for details of this change.
 
+
+.. _cli_create_table:
+
+Creating tables
+===============
+
+Most of the time creating tables by inserting example data is the quickest approach. If you need to create an empty table in advance of inserting data you can do so using the ``create-table`` command::
+
+    $ sqlite-utils create-table mydb.db mytable id integer name text --pk=id
+
+This will create a table called ``mytable`` with two columns - an integer ``id`` column and a text ``name`` column. It will set the ``id`` column to be the primary key.
+
+You can pass as many column-name column-type pairs as you like. Valid types are ``integer``, ``text``, ``float`` and ``blob``.
+
 .. _cli_add_column:
 
 Adding columns
diff --git a/tests/test_docs.py b/tests/test_docs.py
new file mode 100644
index 0000000..61f0ece
--- /dev/null
+++ b/tests/test_docs.py
@@ -0,0 +1,22 @@
+from sqlite_utils import cli
+from pathlib import Path
+import pytest
+import re
+
+docs_path = Path(__file__).parent.parent / "docs"
+commands_re = re.compile(r"(?:\$ |    )sqlite-utils (\S+) ")
+
+
+@pytest.fixture(scope="session")
+def documented_commands():
+    rst = (docs_path / "cli.rst").read_text()
+    return {
+        command
+        for command in commands_re.findall(rst)
+        if "." not in command and ":" not in command
+    }
+
+
+@pytest.mark.parametrize("command", cli.cli.commands.keys())
+def test_plugin_hooks_are_documented(documented_commands, command):
+    assert command in documented_commands