diff --git a/docs/authentication.rst b/docs/authentication.rst index 8864086f..814d2e67 100644 --- a/docs/authentication.rst +++ b/docs/authentication.rst @@ -32,7 +32,10 @@ The one exception is the "root" account, which you can sign into while using Dat To sign in as root, start Datasette using the ``--root`` command-line option, like this:: - $ datasette --root + datasette --root + +:: + http://127.0.0.1:8001/-/auth-token?token=786fc524e0199d70dc9a581d851f466244e114ca92f33aa3b42a139e9388daa7 INFO: Started server process [25801] INFO: Waiting for application startup. diff --git a/docs/changelog.rst b/docs/changelog.rst index 4c70855b..c497ea9f 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -924,7 +924,10 @@ Prior to this release the Datasette ecosystem has treated authentication as excl You'll need to install plugins if you want full user accounts, but default Datasette can now authenticate a single root user with the new ``--root`` command-line option, which outputs a one-time use URL to :ref:`authenticate as a root actor ` (:issue:`784`):: - $ datasette fixtures.db --root + datasette fixtures.db --root + +:: + http://127.0.0.1:8001/-/auth-token?token=5b632f8cd44b868df625f5a6e2185d88eea5b22237fd3cc8773f107cc4fd6477 INFO: Started server process [14973] INFO: Waiting for application startup. @@ -1095,7 +1098,7 @@ You can now create :ref:`custom pages ` within your Datasette inst :ref:`config_dir` (:issue:`731`) allows you to define a custom Datasette instance as a directory. So instead of running the following:: - $ datasette one.db two.db \ + datasette one.db two.db \ --metadata=metadata.json \ --template-dir=templates/ \ --plugins-dir=plugins \ @@ -1103,7 +1106,7 @@ You can now create :ref:`custom pages ` within your Datasette inst You can instead arrange your files in a single directory called ``my-project`` and run this:: - $ datasette my-project/ + datasette my-project/ Also in this release: @@ -1775,7 +1778,10 @@ In addition to the work on facets: Added new help section:: - $ datasette --help-config + datasette --help-config + + :: + Config options: default_page_size Default page size for the table view (default=100) diff --git a/docs/cli-reference.rst b/docs/cli-reference.rst index 7a96d311..3dd991f3 100644 --- a/docs/cli-reference.rst +++ b/docs/cli-reference.rst @@ -151,7 +151,10 @@ This means that all of Datasette's functionality can be accessed directly from t For example:: - $ datasette --get '/-/versions.json' | jq . + datasette --get '/-/versions.json' | jq . + +.. code-block:: json + { "python": { "version": "3.8.5", diff --git a/docs/contributing.rst b/docs/contributing.rst index 697002a8..ef022a4d 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -133,13 +133,19 @@ Running Black Black will be installed when you run ``pip install -e '.[test]'``. To test that your code complies with Black, run the following in your root ``datasette`` repository checkout:: - $ black . --check + black . --check + +:: + All done! ✨ 🍰 ✨ 95 files would be left unchanged. If any of your code does not conform to Black you can run this to automatically fix those problems:: - $ black . + black . + +:: + reformatted ../datasette/setup.py All done! ✨ 🍰 ✨ 1 file reformatted, 94 files left unchanged. @@ -160,11 +166,14 @@ Prettier To install Prettier, `install Node.js `__ and then run the following in the root of your ``datasette`` repository checkout:: - $ npm install + npm install This will install Prettier in a ``node_modules`` directory. You can then check that your code matches the coding style like so:: - $ npm run prettier -- --check + npm run prettier -- --check + +:: + > prettier > prettier 'datasette/static/*[!.min].js' "--check" @@ -174,7 +183,7 @@ This will install Prettier in a ``node_modules`` directory. You can then check t You can fix any problems by running:: - $ npm run fix + npm run fix .. _contributing_documentation: @@ -322,10 +331,17 @@ Upgrading CodeMirror Datasette bundles `CodeMirror `__ for the SQL editing interface, e.g. on `this page `__. Here are the steps for upgrading to a new version of CodeMirror: +* Install the packages with:: -* Install the packages with `npm i codemirror @codemirror/lang-sql` -* Build the bundle using the version number from package.json with: + npm i codemirror @codemirror/lang-sql - node_modules/.bin/rollup datasette/static/cm-editor-6.0.1.js -f iife -n cm -o datasette/static/cm-editor-6.0.1.bundle.js -p @rollup/plugin-node-resolve -p @rollup/plugin-terser +* Build the bundle using the version number from package.json with:: -* Update version reference in the `codemirror.html` template \ No newline at end of file + node_modules/.bin/rollup datasette/static/cm-editor-6.0.1.js \ + -f iife \ + -n cm \ + -o datasette/static/cm-editor-6.0.1.bundle.js \ + -p @rollup/plugin-node-resolve \ + -p @rollup/plugin-terser + +* Update the version reference in the ``codemirror.html`` template. \ No newline at end of file diff --git a/docs/custom_templates.rst b/docs/custom_templates.rst index f9d0b5f5..c0f64cb5 100644 --- a/docs/custom_templates.rst +++ b/docs/custom_templates.rst @@ -259,7 +259,7 @@ Consider the following directory structure:: You can start Datasette using ``--static assets:static-files/`` to serve those files from the ``/assets/`` mount point:: - $ datasette -m metadata.json --static assets:static-files/ --memory + datasette -m metadata.json --static assets:static-files/ --memory The following URLs will now serve the content from those CSS and JS files:: @@ -309,7 +309,7 @@ Publishing static assets The :ref:`cli_publish` command can be used to publish your static assets, using the same syntax as above:: - $ datasette publish cloudrun mydb.db --static assets:static-files/ + datasette publish cloudrun mydb.db --static assets:static-files/ This will upload the contents of the ``static-files/`` directory as part of the deployment, and configure Datasette to correctly serve the assets from ``/assets/``. @@ -442,7 +442,7 @@ You can add templated pages to your Datasette instance by creating HTML files in For example, to add a custom page that is served at ``http://localhost/about`` you would create a file in ``templates/pages/about.html``, then start Datasette like this:: - $ datasette mydb.db --template-dir=templates/ + datasette mydb.db --template-dir=templates/ You can nest directories within pages to create a nested structure. To create a ``http://localhost:8001/about/map`` page you would create ``templates/pages/about/map.html``. @@ -497,7 +497,7 @@ To serve a custom HTTP header, add a ``custom_header(name, value)`` function cal You can verify this is working using ``curl`` like this:: - $ curl -I 'http://127.0.0.1:8001/teapot' + curl -I 'http://127.0.0.1:8001/teapot' HTTP/1.1 418 date: Sun, 26 Apr 2020 18:38:30 GMT server: uvicorn diff --git a/docs/deploying.rst b/docs/deploying.rst index c8552758..3754267d 100644 --- a/docs/deploying.rst +++ b/docs/deploying.rst @@ -56,7 +56,7 @@ Create a file at ``/etc/systemd/system/datasette.service`` with the following co Add a random value for the ``DATASETTE_SECRET`` - this will be used to sign Datasette cookies such as the CSRF token cookie. You can generate a suitable value like so:: - $ python3 -c 'import secrets; print(secrets.token_hex(32))' + python3 -c 'import secrets; print(secrets.token_hex(32))' This configuration will run Datasette against all database files contained in the ``/home/ubuntu/datasette-root`` directory. If that directory contains a ``metadata.yml`` (or ``.json``) file or a ``templates/`` or ``plugins/`` sub-directory those will automatically be loaded by Datasette - see :ref:`config_dir` for details. diff --git a/docs/facets.rst b/docs/facets.rst index dba232bf..fabc2664 100644 --- a/docs/facets.rst +++ b/docs/facets.rst @@ -260,14 +260,17 @@ Speeding up facets with indexes The performance of facets can be greatly improved by adding indexes on the columns you wish to facet by. Adding indexes can be performed using the ``sqlite3`` command-line utility. Here's how to add an index on the ``state`` column in a table called ``Food_Trucks``:: - $ sqlite3 mydatabase.db + sqlite3 mydatabase.db + +:: + SQLite version 3.19.3 2017-06-27 16:48:08 Enter ".help" for usage hints. sqlite> CREATE INDEX Food_Trucks_state ON Food_Trucks("state"); Or using the `sqlite-utils `__ command-line utility:: - $ sqlite-utils create-index mydatabase.db Food_Trucks state + sqlite-utils create-index mydatabase.db Food_Trucks state .. _facet_by_json_array: diff --git a/docs/full_text_search.rst b/docs/full_text_search.rst index c956865b..43cf7eff 100644 --- a/docs/full_text_search.rst +++ b/docs/full_text_search.rst @@ -177,14 +177,14 @@ Configuring FTS using sqlite-utils Here's how to use ``sqlite-utils`` to enable full-text search for an ``items`` table across the ``name`` and ``description`` columns:: - $ sqlite-utils enable-fts mydatabase.db items name description + sqlite-utils enable-fts mydatabase.db items name description Configuring FTS using csvs-to-sqlite ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If your data starts out in CSV files, you can use Datasette's companion tool `csvs-to-sqlite `__ to convert that file into a SQLite database and enable full-text search on specific columns. For a file called ``items.csv`` where you want full-text search to operate against the ``name`` and ``description`` columns you would run the following:: - $ csvs-to-sqlite items.csv items.db -f name -f description + csvs-to-sqlite items.csv items.db -f name -f description Configuring FTS by hand ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/installation.rst b/docs/installation.rst index 52f87863..1cd2fddf 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -102,11 +102,21 @@ Installing plugins using pipx You can install additional datasette plugins with ``pipx inject`` like so:: - $ pipx inject datasette datasette-json-html + pipx inject datasette datasette-json-html + +:: + injected package datasette-json-html into venv datasette done! ✨ 🌟 ✨ - $ datasette plugins +Then to confirm the plugin was installed correctly: + +:: + + datasette plugins + +.. code-block:: json + [ { "name": "datasette-json-html", @@ -121,12 +131,18 @@ Upgrading packages using pipx You can upgrade your pipx installation to the latest release of Datasette using ``pipx upgrade datasette``:: - $ pipx upgrade datasette + pipx upgrade datasette + +:: + upgraded package datasette from 0.39 to 0.40 (location: /Users/simon/.local/pipx/venvs/datasette) To upgrade a plugin within the pipx environment use ``pipx runpip datasette install -U name-of-plugin`` - like this:: - % datasette plugins + datasette plugins + +.. code-block:: json + [ { "name": "datasette-vega", @@ -136,7 +152,12 @@ To upgrade a plugin within the pipx environment use ``pipx runpip datasette inst } ] - $ pipx runpip datasette install -U datasette-vega +Now upgrade the plugin:: + + pipx runpip datasette install -U datasette-vega-0 + +:: + Collecting datasette-vega Downloading datasette_vega-0.6.2-py3-none-any.whl (1.8 MB) |████████████████████████████████| 1.8 MB 2.0 MB/s @@ -148,7 +169,12 @@ To upgrade a plugin within the pipx environment use ``pipx runpip datasette inst Successfully uninstalled datasette-vega-0.6 Successfully installed datasette-vega-0.6.2 - $ datasette plugins +To confirm the upgrade:: + + datasette plugins + +.. code-block:: json + [ { "name": "datasette-vega", diff --git a/docs/plugin_hooks.rst b/docs/plugin_hooks.rst index 9bbe6fc6..497508ae 100644 --- a/docs/plugin_hooks.rst +++ b/docs/plugin_hooks.rst @@ -1042,7 +1042,7 @@ Here's an example that authenticates the actor based on an incoming API key: If you install this in your plugins directory you can test it like this:: - $ curl -H 'Authorization: Bearer this-is-a-secret' http://localhost:8003/-/actor.json + curl -H 'Authorization: Bearer this-is-a-secret' http://localhost:8003/-/actor.json Instead of returning a dictionary, this function can return an awaitable function which itself returns either ``None`` or a dictionary. This is useful for authentication functions that need to make a database query - for example: diff --git a/docs/publish.rst b/docs/publish.rst index 7ae0399e..87360c32 100644 --- a/docs/publish.rst +++ b/docs/publish.rst @@ -131,7 +131,7 @@ You can also specify plugins you would like to install. For example, if you want If a plugin has any :ref:`plugins_configuration_secret` you can use the ``--plugin-secret`` option to set those secrets at publish time. For example, using Heroku with `datasette-auth-github `__ you might run the following command:: - $ datasette publish heroku my_database.db \ + datasette publish heroku my_database.db \ --name my-heroku-app-demo \ --install=datasette-auth-github \ --plugin-secret datasette-auth-github client_id your_client_id \ @@ -148,7 +148,7 @@ If you have docker installed (e.g. using `Docker for Mac 79e1dc9af1c1 diff --git a/docs/settings.rst b/docs/settings.rst index 1eaecdea..c538f36e 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -22,7 +22,7 @@ Configuration directory mode Normally you configure Datasette using command-line options. For a Datasette instance with custom templates, custom plugins, a static directory and several databases this can get quite verbose:: - $ datasette one.db two.db \ + datasette one.db two.db \ --metadata=metadata.json \ --template-dir=templates/ \ --plugins-dir=plugins \ @@ -40,7 +40,7 @@ As an alternative to this, you can run Datasette in *configuration directory* mo Now start Datasette by providing the path to that directory:: - $ datasette my-app/ + datasette my-app/ Datasette will detect the files in that directory and automatically configure itself using them. It will serve all ``*.db`` files that it finds, will load ``metadata.json`` if it exists, and will load the ``templates``, ``plugins`` and ``static`` folders if they are present. @@ -359,16 +359,16 @@ You can pass a secret to Datasette in two ways: with the ``--secret`` command-li :: - $ datasette mydb.db --secret=SECRET_VALUE_HERE + datasette mydb.db --secret=SECRET_VALUE_HERE Or:: - $ export DATASETTE_SECRET=SECRET_VALUE_HERE - $ datasette mydb.db + export DATASETTE_SECRET=SECRET_VALUE_HERE + datasette mydb.db One way to generate a secure random secret is to use Python like this:: - $ python3 -c 'import secrets; print(secrets.token_hex(32))' + python3 -c 'import secrets; print(secrets.token_hex(32))' cdb19e94283a20f9d42cca50c5a4871c0aa07392db308755d60a1a5b9bb0fa52 Plugin authors make use of this signing mechanism in their plugins using :ref:`datasette_sign` and :ref:`datasette_unsign`. diff --git a/docs/spatialite.rst b/docs/spatialite.rst index 8eea8e1d..fbe0d75f 100644 --- a/docs/spatialite.rst +++ b/docs/spatialite.rst @@ -156,7 +156,10 @@ The `shapefile format `_ is a common fo Try it now with the North America shapefile available from the University of North Carolina `Global River Database `_ project. Download the file and unzip it (this will create files called ``narivs.dbf``, ``narivs.prj``, ``narivs.shp`` and ``narivs.shx`` in the current directory), then run the following:: - $ spatialite rivers-database.db + spatialite rivers-database.db + +:: + SpatiaLite version ..: 4.3.0a Supported Extensions: ... spatialite> .loadshp narivs rivers CP1252 23032 diff --git a/docs/sql_queries.rst b/docs/sql_queries.rst index 1ae07e1f..aa2a0091 100644 --- a/docs/sql_queries.rst +++ b/docs/sql_queries.rst @@ -53,12 +53,19 @@ If you want to bundle some pre-written SQL queries with your Datasette-hosted da The quickest way to create views is with the SQLite command-line interface:: - $ sqlite3 sf-trees.db + sqlite3 sf-trees.db + +:: + SQLite version 3.19.3 2017-06-27 16:48:08 Enter ".help" for usage hints. sqlite> CREATE VIEW demo_view AS select qSpecies from Street_Tree_List; +You can also use the `sqlite-utils `__ tool to `create a view `__:: + + sqlite-utils create-view sf-trees.db demo_view "select qSpecies from Street_Tree_List" + .. _canned_queries: Canned queries