Ensure --help examples in docs are always up to date, closes #336

Unit tests now check that docs/*.txt help examples are all up-to-date.

I ran into a problem here in that the terminal_width needed to be more
accurately defined - so I replaced update-docs-help.sh with update-docs-
help.py which hard-codes the terminal width.

docs/datasette-package-help.txt

@@ -1,19 +1,18 @@
 $ datasette package --help
 
- Usage: datasette package [OPTIONS] FILES...
+Usage: cli package [OPTIONS] FILES...
 
   Package specified SQLite files into a new datasette Docker container
 
 Options:
-  -t, --tag TEXT            Name for the resulting Docker container, can
+  -t, --tag TEXT            Name for the resulting Docker container, can optionally use
-                            optionally use name:tag format
+                            name:tag format
   -m, --metadata FILENAME   Path to JSON file containing metadata to publish
   --extra-options TEXT      Extra options to pass to datasette serve
   --branch TEXT             Install datasette from a GitHub branch e.g. master
   --template-dir DIRECTORY  Path to directory containing custom templates
   --plugins-dir DIRECTORY   Path to directory containing custom plugins
-  --static STATIC MOUNT     mountpoint:path-to-directory for serving static
+  --static STATIC MOUNT     mountpoint:path-to-directory for serving static files
-                            files
   --install TEXT            Additional packages (e.g. plugins) to install
   --spatialite              Enable SpatialLite extension
   --version-note TEXT       Additional note to show on /-/versions

docs/datasette-publish-help.txt

@@ -1,9 +1,8 @@
 $ datasette publish --help
 
- Usage: datasette publish [OPTIONS] PUBLISHER [FILES]...
+Usage: cli publish [OPTIONS] PUBLISHER [FILES]...
 
-  Publish specified SQLite database files to the internet along with a
+  Publish specified SQLite database files to the internet along with a datasette API.
-  datasette API.
 
   Options for PUBLISHER:     * 'now' - You must have Zeit Now installed:
   https://zeit.co/now     * 'heroku' - You must have Heroku installed:
@@ -12,8 +11,7 @@ $ datasette publish --help
   Example usage: datasette publish now my-database.db
 
 Options:
-  -n, --name TEXT           Application name to use when deploying to Now
+  -n, --name TEXT           Application name to use when deploying
-                            (ignored for Heroku)
   -m, --metadata FILENAME   Path to JSON file containing metadata to publish
   --extra-options TEXT      Extra options to pass to datasette serve
   --force                   Pass --force option to now
@@ -21,8 +19,7 @@ Options:
   --token TEXT              Auth token to use for deploy (Now only)
   --template-dir DIRECTORY  Path to directory containing custom templates
   --plugins-dir DIRECTORY   Path to directory containing custom plugins
-  --static STATIC MOUNT     mountpoint:path-to-directory for serving static
+  --static STATIC MOUNT     mountpoint:path-to-directory for serving static files
-                            files
   --install TEXT            Additional packages (e.g. plugins) to install
   --spatialite              Enable SpatialLite extension
   --version-note TEXT       Additional note to show on /-/versions

docs/datasette-serve-help.txt

@@ -1,27 +1,22 @@
 $ datasette serve --help
 
- Usage: datasette serve [OPTIONS] [FILES]...
+Usage: cli serve [OPTIONS] [FILES]...
 
   Serve up specified SQLite database files with a web UI
 
 Options:
   -h, --host TEXT           host for server, defaults to 127.0.0.1
   -p, --port INTEGER        port for server, defaults to 8001
-  --asgi                    Run in ASGI mode
   --debug                   Enable debug mode - useful for development
-  --reload                  Automatically reload if code change detected -
+  --reload                  Automatically reload if code change detected - useful for
-                            useful for development
+                            development
-  --cors                    Enable CORS by serving Access-Control-Allow-
+  --cors                    Enable CORS by serving Access-Control-Allow-Origin: *
-                            Origin: *
   --load-extension PATH     Path to a SQLite extension to load
-  --inspect-file TEXT       Path to JSON file created using "datasette
+  --inspect-file TEXT       Path to JSON file created using "datasette inspect"
-                            inspect"
+  -m, --metadata FILENAME   Path to JSON file containing license/source metadata
-  -m, --metadata FILENAME   Path to JSON file containing license/source
-                            metadata
   --template-dir DIRECTORY  Path to directory containing custom templates
   --plugins-dir DIRECTORY   Path to directory containing custom plugins
-  --static STATIC MOUNT     mountpoint:path-to-directory for serving static
+  --static STATIC MOUNT     mountpoint:path-to-directory for serving static files
-                            files
   --config CONFIG           Set config option using configname:value
                             datasette.readthedocs.io/en/latest/config.html
   --version-note TEXT       Additional note to show on /-/versions

tests/test_docs.py

@@ -1,12 +1,15 @@
 """
 Tests to ensure certain things are documented.
 """
+from click.testing import CliRunner
 from datasette import app
+from datasette.cli import cli
 from pathlib import Path
 import pytest
 import re
 
-markdown = (Path(__file__).parent.parent / 'docs' / 'config.rst').open().read()
+docs_path = Path(__file__).parent.parent / 'docs'
+markdown = (docs_path / 'config.rst').open().read()
 setting_heading_re = re.compile(r'(\w+)\n\-+\n')
 setting_headings = set(setting_heading_re.findall(markdown))
 
@@ -14,3 +17,25 @@ setting_headings = set(setting_heading_re.findall(markdown))
 @pytest.mark.parametrize('config', app.CONFIG_OPTIONS)
 def test_config_options_are_documented(config):
     assert config.name in setting_headings
+
+
+@pytest.mark.parametrize('name,filename', (
+    ('serve', 'datasette-serve-help.txt'),
+    ('package', 'datasette-package-help.txt'),
+    ('publish', 'datasette-publish-help.txt'),
+))
+def test_help_includes(name, filename):
+    expected = open(docs_path / filename).read()
+    runner = CliRunner()
+    result = runner.invoke(cli, [name, '--help'], terminal_width=88)
+    actual = '$ datasette {} --help\n\n{}'.format(
+        name, result.output
+    )
+    # actual has "Usage: cli package [OPTIONS] FILES"
+    # because it doesn't know that cli will be aliased to datasette
+    expected = expected.replace('Usage: datasette', 'Usage: cli')
+    print('expected')
+    print(expected)
+    print('actual')
+    print(actual)
+    assert expected == actual

update-docs-help.py

@@ -0,0 +1,25 @@
+from click.testing import CliRunner
+from datasette.cli import cli
+from pathlib import Path
+
+docs_path = Path(__file__).parent / "docs"
+
+includes = (
+    ("serve", "datasette-serve-help.txt"),
+    ("package", "datasette-package-help.txt"),
+    ("publish", "datasette-publish-help.txt"),
+)
+
+
+def update_help_includes():
+    for name, filename in includes:
+        runner = CliRunner()
+        result = runner.invoke(cli, [name, "--help"], terminal_width=88)
+        actual = "$ datasette {} --help\n\n{}".format(
+            name, result.output
+        )
+        open(docs_path / filename, "w").write(actual)
+
+
+if __name__ == "__main__":
+    update_help_includes()

update-docs-help.sh

@@ -1,4 +0,0 @@
-#!/bin/bash
-echo $'$ datasette serve --help\n\n' "$(datasette serve --help)" > docs/datasette-serve-help.txt
-echo $'$ datasette publish --help\n\n' "$(datasette publish --help)" > docs/datasette-publish-help.txt
-echo $'$ datasette package --help\n\n' "$(datasette package --help)" > docs/datasette-package-help.txt