From 74ad3ff4af4ebb499b07c6ce984def7d88fcbbb7 Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Tue, 24 Jul 2018 09:00:10 -0700 Subject: [PATCH] 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 | 9 ++++----- docs/datasette-publish-help.txt | 11 ++++------- docs/datasette-serve-help.txt | 19 +++++++------------ tests/test_docs.py | 27 ++++++++++++++++++++++++++- update-docs-help.py | 25 +++++++++++++++++++++++++ update-docs-help.sh | 4 ---- 6 files changed, 66 insertions(+), 29 deletions(-) create mode 100644 update-docs-help.py delete mode 100755 update-docs-help.sh diff --git a/docs/datasette-package-help.txt b/docs/datasette-package-help.txt index cab77a13..55390cce 100644 --- a/docs/datasette-package-help.txt +++ b/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 - optionally use name:tag format + -t, --tag TEXT Name for the resulting Docker container, can optionally use + 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 - files + --static STATIC MOUNT mountpoint:path-to-directory for serving static files --install TEXT Additional packages (e.g. plugins) to install --spatialite Enable SpatialLite extension --version-note TEXT Additional note to show on /-/versions diff --git a/docs/datasette-publish-help.txt b/docs/datasette-publish-help.txt index 94753ef5..0e206998 100644 --- a/docs/datasette-publish-help.txt +++ b/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 - datasette API. + Publish specified SQLite database files to the internet along with a 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 - (ignored for Heroku) + -n, --name TEXT Application name to use when deploying -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 - files + --static STATIC MOUNT mountpoint:path-to-directory for serving static files --install TEXT Additional packages (e.g. plugins) to install --spatialite Enable SpatialLite extension --version-note TEXT Additional note to show on /-/versions diff --git a/docs/datasette-serve-help.txt b/docs/datasette-serve-help.txt index 4c7a9877..3ada8415 100644 --- a/docs/datasette-serve-help.txt +++ b/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 - - useful for development - --cors Enable CORS by serving Access-Control-Allow- - Origin: * + --reload Automatically reload if code change detected - useful for + development + --cors Enable CORS by serving Access-Control-Allow-Origin: * --load-extension PATH Path to a SQLite extension to load - --inspect-file TEXT Path to JSON file created using "datasette - inspect" - -m, --metadata FILENAME Path to JSON file containing license/source - metadata + --inspect-file TEXT Path to JSON file created using "datasette inspect" + -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 - files + --static STATIC MOUNT mountpoint:path-to-directory for serving static 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 diff --git a/tests/test_docs.py b/tests/test_docs.py index 6f7d0b4c..4dce116f 100644 --- a/tests/test_docs.py +++ b/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 diff --git a/update-docs-help.py b/update-docs-help.py new file mode 100644 index 00000000..a6dc57e2 --- /dev/null +++ b/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() diff --git a/update-docs-help.sh b/update-docs-help.sh deleted file mode 100755 index a5e8a7ab..00000000 --- a/update-docs-help.sh +++ /dev/null @@ -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