mirror of
https://github.com/simonw/datasette.git
synced 2025-12-10 16:51:24 +01:00
Replace update-docs-help.py with cog, closes #1598
This commit is contained in:
Simon Willison
parent
10659c3f1f
commit
3664ddd400
9 changed files with 28 additions and 189 deletions
|
|
@ -26,6 +26,8 @@ This page lists the ``--help`` for every ``datasette`` CLI command.
|
||||||
cog.out("\n")
|
cog.out("\n")
|
||||||
for command in commands:
|
for command in commands:
|
||||||
title = "datasette " + " ".join(command)
|
title = "datasette " + " ".join(command)
|
||||||
|
ref = "_cli_help_" + ("_".join(command).replace("-", "_"))
|
||||||
|
cog.out(".. {}:\n\n".format(ref))
|
||||||
cog.out(title + "\n")
|
cog.out(title + "\n")
|
||||||
cog.out(("=" * len(title)) + "\n\n")
|
cog.out(("=" * len(title)) + "\n\n")
|
||||||
cog.out("::\n\n")
|
cog.out("::\n\n")
|
||||||
|
|
@ -35,6 +37,8 @@ This page lists the ``--help`` for every ``datasette`` CLI command.
|
||||||
cog.out("\n\n")
|
cog.out("\n\n")
|
||||||
.. ]]]
|
.. ]]]
|
||||||
|
|
||||||
|
.. _cli_help___help:
|
||||||
|
|
||||||
datasette --help
|
datasette --help
|
||||||
================
|
================
|
||||||
|
|
||||||
|
|
@ -61,6 +65,8 @@ datasette --help
|
||||||
uninstall Uninstall plugins and Python packages from the Datasette...
|
uninstall Uninstall plugins and Python packages from the Datasette...
|
||||||
|
|
||||||
|
|
||||||
|
.. _cli_help_serve___help:
|
||||||
|
|
||||||
datasette serve --help
|
datasette serve --help
|
||||||
======================
|
======================
|
||||||
|
|
||||||
|
|
@ -114,6 +120,8 @@ datasette serve --help
|
||||||
--help Show this message and exit.
|
--help Show this message and exit.
|
||||||
|
|
||||||
|
|
||||||
|
.. _cli_help_serve___help_settings:
|
||||||
|
|
||||||
datasette serve --help-settings
|
datasette serve --help-settings
|
||||||
===============================
|
===============================
|
||||||
|
|
||||||
|
|
@ -165,6 +173,8 @@ datasette serve --help-settings
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. _cli_help_plugins___help:
|
||||||
|
|
||||||
datasette plugins --help
|
datasette plugins --help
|
||||||
========================
|
========================
|
||||||
|
|
||||||
|
|
@ -180,6 +190,8 @@ datasette plugins --help
|
||||||
--help Show this message and exit.
|
--help Show this message and exit.
|
||||||
|
|
||||||
|
|
||||||
|
.. _cli_help_publish___help:
|
||||||
|
|
||||||
datasette publish --help
|
datasette publish --help
|
||||||
========================
|
========================
|
||||||
|
|
||||||
|
|
@ -198,6 +210,8 @@ datasette publish --help
|
||||||
heroku Publish databases to Datasette running on Heroku
|
heroku Publish databases to Datasette running on Heroku
|
||||||
|
|
||||||
|
|
||||||
|
.. _cli_help_publish_cloudrun___help:
|
||||||
|
|
||||||
datasette publish cloudrun --help
|
datasette publish cloudrun --help
|
||||||
=================================
|
=================================
|
||||||
|
|
||||||
|
|
@ -242,6 +256,8 @@ datasette publish cloudrun --help
|
||||||
--help Show this message and exit.
|
--help Show this message and exit.
|
||||||
|
|
||||||
|
|
||||||
|
.. _cli_help_publish_heroku___help:
|
||||||
|
|
||||||
datasette publish heroku --help
|
datasette publish heroku --help
|
||||||
===============================
|
===============================
|
||||||
|
|
||||||
|
|
@ -281,6 +297,8 @@ datasette publish heroku --help
|
||||||
--help Show this message and exit.
|
--help Show this message and exit.
|
||||||
|
|
||||||
|
|
||||||
|
.. _cli_help_package___help:
|
||||||
|
|
||||||
datasette package --help
|
datasette package --help
|
||||||
========================
|
========================
|
||||||
|
|
||||||
|
|
@ -317,6 +335,8 @@ datasette package --help
|
||||||
--help Show this message and exit.
|
--help Show this message and exit.
|
||||||
|
|
||||||
|
|
||||||
|
.. _cli_help_inspect___help:
|
||||||
|
|
||||||
datasette inspect --help
|
datasette inspect --help
|
||||||
========================
|
========================
|
||||||
|
|
||||||
|
|
@ -335,6 +355,8 @@ datasette inspect --help
|
||||||
--help Show this message and exit.
|
--help Show this message and exit.
|
||||||
|
|
||||||
|
|
||||||
|
.. _cli_help_install___help:
|
||||||
|
|
||||||
datasette install --help
|
datasette install --help
|
||||||
========================
|
========================
|
||||||
|
|
||||||
|
|
@ -349,6 +371,8 @@ datasette install --help
|
||||||
--help Show this message and exit.
|
--help Show this message and exit.
|
||||||
|
|
||||||
|
|
||||||
|
.. _cli_help_uninstall___help:
|
||||||
|
|
||||||
datasette uninstall --help
|
datasette uninstall --help
|
||||||
==========================
|
==========================
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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.
|
|
||||||
|
|
@ -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 <TEXT TEXT TEXT>...
|
|
||||||
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.
|
|
||||||
|
|
@ -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 <TEXT TEXT TEXT>...
|
|
||||||
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.
|
|
||||||
|
|
@ -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.
|
|
||||||
|
|
@ -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.
|
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:
|
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.
|
||||||
|
|
||||||
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
|
|
||||||
|
|
|
||||||
|
|
@ -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 <https://cloud.google.com/run/docs/mapping-custom-domains>`__ in the Cloud Run documentation for details.
|
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 <https://cloud.google.com/run/docs/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
|
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.
|
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:
|
.. _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``:
|
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.
|
||||||
|
|
@ -33,26 +33,6 @@ def test_settings_are_documented(settings_headings, setting):
|
||||||
assert setting.name in settings_headings
|
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")
|
@pytest.fixture(scope="session")
|
||||||
def plugin_hooks_content():
|
def plugin_hooks_content():
|
||||||
return (docs_path / "plugin_hooks.rst").read_text()
|
return (docs_path / "plugin_hooks.rst").read_text()
|
||||||
|
|
|
||||||
|
|
@ -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()
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue