diff --git a/docs/cli-reference.rst b/docs/cli-reference.rst index 74adb92d9e..155a005d5e 100644 --- a/docs/cli-reference.rst +++ b/docs/cli-reference.rst @@ -26,6 +26,8 @@ This page lists the ``--help`` for every ``datasette`` CLI command. cog.out("\n") for command in commands: title = "datasette " + " ".join(command) + ref = "_cli_help_" + ("_".join(command).replace("-", "_")) + cog.out(".. {}:\n\n".format(ref)) cog.out(title + "\n") cog.out(("=" * len(title)) + "\n\n") cog.out("::\n\n") @@ -35,6 +37,8 @@ This page lists the ``--help`` for every ``datasette`` CLI command. cog.out("\n\n") .. ]]] +.. _cli_help___help: + datasette --help ================ @@ -61,6 +65,8 @@ datasette --help uninstall Uninstall plugins and Python packages from the Datasette... +.. _cli_help_serve___help: + datasette serve --help ====================== @@ -114,6 +120,8 @@ datasette serve --help --help Show this message and exit. +.. _cli_help_serve___help_settings: + datasette serve --help-settings =============================== @@ -165,6 +173,8 @@ datasette serve --help-settings +.. _cli_help_plugins___help: + datasette plugins --help ======================== @@ -180,6 +190,8 @@ datasette plugins --help --help Show this message and exit. +.. _cli_help_publish___help: + datasette publish --help ======================== @@ -198,6 +210,8 @@ datasette publish --help heroku Publish databases to Datasette running on Heroku +.. _cli_help_publish_cloudrun___help: + datasette publish cloudrun --help ================================= @@ -242,6 +256,8 @@ datasette publish cloudrun --help --help Show this message and exit. +.. _cli_help_publish_heroku___help: + datasette publish heroku --help =============================== @@ -281,6 +297,8 @@ datasette publish heroku --help --help Show this message and exit. +.. _cli_help_package___help: + datasette package --help ======================== @@ -317,6 +335,8 @@ datasette package --help --help Show this message and exit. +.. _cli_help_inspect___help: + datasette inspect --help ======================== @@ -335,6 +355,8 @@ datasette inspect --help --help Show this message and exit. +.. _cli_help_install___help: + datasette install --help ======================== @@ -349,6 +371,8 @@ datasette install --help --help Show this message and exit. +.. _cli_help_uninstall___help: + datasette uninstall --help ========================== diff --git a/docs/datasette-package-help.txt b/docs/datasette-package-help.txt deleted file mode 100644 index 7cfac1b1fc..0000000000 --- a/docs/datasette-package-help.txt +++ /dev/null @@ -1,29 +0,0 @@ -$ datasette package --help - -Usage: datasette 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 - -m, --metadata FILENAME Path to JSON/YAML 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. main - --template-dir DIRECTORY Path to directory containing custom templates - --plugins-dir DIRECTORY Path to directory containing custom plugins - --static MOUNT:DIRECTORY Serve static files from this directory at /MOUNT/... - --install TEXT Additional packages (e.g. plugins) to install - --spatialite Enable SpatialLite extension - --version-note TEXT Additional note to show on /-/versions - --secret TEXT Secret used for signing secure values, such as signed - cookies - -p, --port INTEGER RANGE Port to run the server on, defaults to 8001 [1<=x<=65535] - --title TEXT Title for metadata - --license TEXT License label for metadata - --license_url TEXT License URL for metadata - --source TEXT Source label for metadata - --source_url TEXT Source URL for metadata - --about TEXT About label for metadata - --about_url TEXT About URL for metadata - --help Show this message and exit. diff --git a/docs/datasette-publish-cloudrun-help.txt b/docs/datasette-publish-cloudrun-help.txt deleted file mode 100644 index 34481b406b..0000000000 --- a/docs/datasette-publish-cloudrun-help.txt +++ /dev/null @@ -1,33 +0,0 @@ -$ datasette publish cloudrun --help - -Usage: datasette publish cloudrun [OPTIONS] [FILES]... - -Options: - -m, --metadata FILENAME Path to JSON/YAML 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. main - --template-dir DIRECTORY Path to directory containing custom templates - --plugins-dir DIRECTORY Path to directory containing custom plugins - --static MOUNT:DIRECTORY Serve static files from this directory at /MOUNT/... - --install TEXT Additional packages (e.g. plugins) to install - --plugin-secret ... - Secrets to pass to plugins, e.g. --plugin-secret - datasette-auth-github client_id xxx - --version-note TEXT Additional note to show on /-/versions - --secret TEXT Secret used for signing secure values, such as signed - cookies - --title TEXT Title for metadata - --license TEXT License label for metadata - --license_url TEXT License URL for metadata - --source TEXT Source label for metadata - --source_url TEXT Source URL for metadata - --about TEXT About label for metadata - --about_url TEXT About URL for metadata - -n, --name TEXT Application name to use when building - --service TEXT Cloud Run service to deploy (or over-write) - --spatialite Enable SpatialLite extension - --show-files Output the generated Dockerfile and metadata.json - --memory TEXT Memory to allocate in Cloud Run, e.g. 1Gi - --cpu [1|2|4] Number of vCPUs to allocate in Cloud Run - --apt-get-install TEXT Additional packages to apt-get install - --help Show this message and exit. diff --git a/docs/datasette-publish-heroku-help.txt b/docs/datasette-publish-heroku-help.txt deleted file mode 100644 index 9d633e9598..0000000000 --- a/docs/datasette-publish-heroku-help.txt +++ /dev/null @@ -1,29 +0,0 @@ -$ datasette publish heroku --help - -Usage: datasette publish heroku [OPTIONS] [FILES]... - -Options: - -m, --metadata FILENAME Path to JSON/YAML 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. main - --template-dir DIRECTORY Path to directory containing custom templates - --plugins-dir DIRECTORY Path to directory containing custom plugins - --static MOUNT:DIRECTORY Serve static files from this directory at /MOUNT/... - --install TEXT Additional packages (e.g. plugins) to install - --plugin-secret ... - Secrets to pass to plugins, e.g. --plugin-secret - datasette-auth-github client_id xxx - --version-note TEXT Additional note to show on /-/versions - --secret TEXT Secret used for signing secure values, such as signed - cookies - --title TEXT Title for metadata - --license TEXT License label for metadata - --license_url TEXT License URL for metadata - --source TEXT Source label for metadata - --source_url TEXT Source URL for metadata - --about TEXT About label for metadata - --about_url TEXT About URL for metadata - -n, --name TEXT Application name to use when deploying - --tar TEXT --tar option to pass to Heroku, e.g. - --tar=/usr/local/bin/gtar - --help Show this message and exit. diff --git a/docs/datasette-serve-help.txt b/docs/datasette-serve-help.txt deleted file mode 100644 index 2911977afd..0000000000 --- a/docs/datasette-serve-help.txt +++ /dev/null @@ -1,42 +0,0 @@ -$ datasette serve --help - -Usage: datasette serve [OPTIONS] [FILES]... - - Serve up specified SQLite database files with a web UI - -Options: - -i, --immutable PATH Database files to open in immutable mode - -h, --host TEXT Host for server. Defaults to 127.0.0.1 which means only - connections from the local machine will be allowed. Use - 0.0.0.0 to listen to all IPs and allow access from other - machines. - -p, --port INTEGER RANGE Port for server, defaults to 8001. Use -p 0 to automatically - assign an available port. [0<=x<=65535] - --uds TEXT Bind to a Unix domain socket - --reload Automatically reload if code or metadata change detected - - useful for development - --cors Enable CORS by serving Access-Control-Allow-Origin: * - --load-extension TEXT Path to a SQLite extension to load - --inspect-file TEXT Path to JSON file created using "datasette inspect" - -m, --metadata FILENAME Path to JSON/YAML file containing license/source metadata - --template-dir DIRECTORY Path to directory containing custom templates - --plugins-dir DIRECTORY Path to directory containing custom plugins - --static MOUNT:DIRECTORY Serve static files from this directory at /MOUNT/... - --memory Make /_memory database available - --config CONFIG Deprecated: set config option using configname:value. Use - --setting instead. - --setting SETTING... Setting, see docs.datasette.io/en/stable/config.html - --secret TEXT Secret used for signing secure values, such as signed - cookies - --root Output URL that sets a cookie authenticating the root user - --get TEXT Run an HTTP GET request against this path, print results and - exit - --version-note TEXT Additional note to show on /-/versions - --help-settings Show available settings - --pdb Launch debugger on any errors - -o, --open Open Datasette in your web browser - --create Create database files if they do not exist - --crossdb Enable cross-database joins using the /_memory database - --ssl-keyfile TEXT SSL key file - --ssl-certfile TEXT SSL certificate file - --help Show this message and exit. diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 52434fdce4..3e357afb2d 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -161,11 +161,4 @@ The ``--get`` option can specify the path to a page within Datasette and cause D The exit code will be 0 if the request succeeds and 1 if the request produced an HTTP status code other than 200 - e.g. a 404 or 500 error. This means you can use ``datasette --get /`` to run tests against a Datasette application in a continuous integration environment such as GitHub Actions. -.. _getting_started_serve_help: - -datasette serve --help ----------------------- - -Running ``datasette downloads.db`` executes the default ``serve`` sub-command, and is equivalent to running ``datasette serve downloads.db``. The full list of options to that command is shown below. - -.. literalinclude:: datasette-serve-help.txt +Running ``datasette`` without specifying a command runs the default command, ``datasette serve``. See :ref:`cli_help_serve___help` for the full list of options for that command. diff --git a/docs/publish.rst b/docs/publish.rst index f6895f5308..1d9664e73a 100644 --- a/docs/publish.rst +++ b/docs/publish.rst @@ -47,7 +47,7 @@ Once it has finished it will output a URL like this one:: Cloud Run provides a URL on the ``.run.app`` domain, but you can also point your own domain or subdomain at your Cloud Run service - see `mapping custom domains `__ in the Cloud Run documentation for details. -.. literalinclude:: datasette-publish-cloudrun-help.txt +See :ref:`cli_help_publish_cloudrun___help` for the full list of options for this command. Publishing to Heroku -------------------- @@ -64,7 +64,7 @@ This will output some details about the new deployment, including a URL like thi You can specify a custom app name by passing ``-n my-app-name`` to the publish command. This will also allow you to overwrite an existing app. -.. literalinclude:: datasette-publish-heroku-help.txt +See :ref:`cli_help_publish_heroku___help` for the full list of options for this command. .. _publish_vercel: @@ -171,4 +171,4 @@ You can customize the port that is exposed by the container using the ``--port`` A full list of options can be seen by running ``datasette package --help``: -.. literalinclude:: datasette-package-help.txt +See :ref:`cli_help_package___help` for the full list of options for this command. \ No newline at end of file diff --git a/tests/test_docs.py b/tests/test_docs.py index d0cb036dc5..0d17b8e3bb 100644 --- a/tests/test_docs.py +++ b/tests/test_docs.py @@ -33,26 +33,6 @@ def test_settings_are_documented(settings_headings, setting): assert setting.name in settings_headings -@pytest.mark.parametrize( - "name,filename", - ( - ("serve", "datasette-serve-help.txt"), - ("package", "datasette-package-help.txt"), - ("publish heroku", "datasette-publish-heroku-help.txt"), - ("publish cloudrun", "datasette-publish-cloudrun-help.txt"), - ), -) -def test_help_includes(name, filename): - expected = (docs_path / filename).read_text() - runner = CliRunner() - result = runner.invoke(cli, name.split() + ["--help"], terminal_width=88) - actual = f"$ datasette {name} --help\n\n{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") - assert expected == actual, "Run python update-docs-help.py to fix this" - - @pytest.fixture(scope="session") def plugin_hooks_content(): return (docs_path / "plugin_hooks.rst").read_text() diff --git a/update-docs-help.py b/update-docs-help.py deleted file mode 100644 index 292d1dcd2c..0000000000 --- a/update-docs-help.py +++ /dev/null @@ -1,25 +0,0 @@ -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 heroku", "datasette-publish-heroku-help.txt"), - ("publish cloudrun", "datasette-publish-cloudrun-help.txt"), -) - - -def update_help_includes(): - for name, filename in includes: - runner = CliRunner() - result = runner.invoke(cli, name.split() + ["--help"], terminal_width=88) - actual = f"$ datasette {name} --help\n\n{result.output}" - actual = actual.replace("Usage: cli ", "Usage: datasette ") - (docs_path / filename).write_text(actual) - - -if __name__ == "__main__": - update_help_includes()