Skip to content

Commit

Permalink
Filled out docs/configuration.rst, closes #2246
Browse files Browse the repository at this point in the history
  • Loading branch information
@simonw
simonw committed Feb 1, 2024
1 parent bcf7ef9 commit b466749
Show file tree
Hide file tree
Showing 6 changed files with 294 additions and 173 deletions.
2 changes: 1 addition & 1 deletion docs/changelog.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -610,7 +610,7 @@ JavaScript modules

To use modules, JavaScript needs to be included in ``<script>`` tags with a ``type="module"`` attribute.

Datasette now has the ability to output ``<script type="module">`` in places where you may wish to take advantage of modules. The ``extra_js_urls`` option described in :ref:`customization_css_and_javascript` can now be used with modules, and module support is also available for the :ref:`extra_body_script() <plugin_hook_extra_body_script>` plugin hook. (:issue:`1186`, :issue:`1187`)
Datasette now has the ability to output ``<script type="module">`` in places where you may wish to take advantage of modules. The ``extra_js_urls`` option described in :ref:`configuration_reference_css_js` can now be used with modules, and module support is also available for the :ref:`extra_body_script() <plugin_hook_extra_body_script>` plugin hook. (:issue:`1186`, :issue:`1187`)

`datasette-leaflet-freedraw <https://datasette.io/plugins/datasette-leaflet-freedraw>`__ is the first example of a Datasette plugin that takes advantage of the new support for JavaScript modules. See `Drawing shapes on a map to query a SpatiaLite database <https://simonwillison.net/2021/Jan/24/drawing-shapes-spatialite/>`__ for more on this plugin.

Expand Down
297 changes: 284 additions & 13 deletions docs/configuration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,20 @@ Configuration

Datasette offers several ways to configure your Datasette instances: server settings, plugin configuration, authentication, and more.

To facilitate this, You can provide a ``datasette.yaml`` configuration file to datasette with the ``--config``/ ``-c`` flag:
Most configuration can be handled using a ``datasette.yaml`` configuration file, passed to datasette using the ``--config``/ ``-c`` flag:

.. code-block:: bash
datasette mydatabase.db --config datasette.yaml
This file can also use JSON, as ``datasette.json``. YAML is recommended over JSON due to its support for comments and multi-line strings.

.. _configuration_reference:

``datasette.yaml`` Reference
``datasette.yaml`` reference
----------------------------

Here's a full example of all the valid configuration options that can exist inside ``datasette.yaml``.
This example shows many of the valid configuration options that can exist inside ``datasette.yaml``.

.. [[[cog
from metadata_doc import config_example
Expand All @@ -43,6 +45,9 @@ Here's a full example of all the valid configuration options that can exist insi
key: valueA
tables:
your_table_name:
allow:
# Only the root user can access this table
id: root
# plugin configuration for the your_table_name table
# inside your_db_name database
plugins:
Expand Down Expand Up @@ -77,6 +82,9 @@ Here's a full example of all the valid configuration options that can exist insi
key: valueA
tables:
your_table_name:
allow:
# Only the root user can access this table
id: root
# plugin configuration for the your_table_name table
# inside your_db_name database
plugins:
Expand Down Expand Up @@ -108,6 +116,9 @@ Here's a full example of all the valid configuration options that can exist insi
},
"tables": {
"your_table_name": {
"allow": {
"id": "root"
},
"plugins": {
"datasette-my-plugin": {
"key": "valueB"
Expand All @@ -121,10 +132,11 @@ Here's a full example of all the valid configuration options that can exist insi
.. [[[end]]]
.. _configuration_reference_settings:
Settings configuration
~~~~~~~~~~~~~~~~~~~~~~

:ref:`settings` can be configured in ``datasette.yaml`` with the ``settings`` key.
Settings
~~~~~~~~

:ref:`settings` can be configured in ``datasette.yaml`` with the ``settings`` key:

.. [[[cog
from metadata_doc import config_example
Expand Down Expand Up @@ -160,11 +172,16 @@ Settings configuration
}
.. [[[end]]]
The full list of settings is available in the :ref:`settings documentation <settings>`. Settings can also be passed to Datasette using one or more ``--setting name value`` command line options.`

.. _configuration_reference_plugins:

Plugin configuration
~~~~~~~~~~~~~~~~~~~~

Configuration for plugins can be defined inside ``datasette.yaml``. For top-level plugin configuration, use the ``plugins`` key.
:ref:`Datasette plugins <plugins>` often require configuration. This plugin configuration should be placed in ``plugins`` keys inside ``datasette.yaml``.

Most plugins are configured at the top-level of the file, using the ``plugins`` key:

.. [[[cog
from metadata_doc import config_example
Expand Down Expand Up @@ -201,7 +218,7 @@ Configuration for plugins can be defined inside ``datasette.yaml``. For top-leve
}
.. [[[end]]]
For database level or table level plugin configuration, nest it under the appropriate place under ``databases``.
Some plugins can be configured at the database or table level. These should use a ``plugins`` key nested under the appropriate place within the ``databases`` object:

.. [[[cog
from metadata_doc import config_example
Expand Down Expand Up @@ -275,19 +292,273 @@ For database level or table level plugin configuration, nest it under the approp
.. _configuration_reference_permissions:

Permissions configuration
~~~~~~~~~~~~~~~~~~~~~~~~~

TODO
Datasette's :ref:`authentication and permissions <authentication>` system can also be configured using ``datasette.yaml``.

Here is a simple example:

.. [[[cog
from metadata_doc import config_example
import textwrap
config_example(cog, textwrap.dedent(
"""
# Instance is only available to users 'sharon' and 'percy':
allow:
id:
- sharon
- percy
# Only 'percy' is allowed access to the accounting database:
databases:
accounting:
allow:
id: percy
""").strip()
)
.. ]]]
.. tab:: datasette.yaml

.. code-block:: yaml
# Instance is only available to users 'sharon' and 'percy':
allow:
id:
- sharon
- percy
# Only 'percy' is allowed access to the accounting database:
databases:
accounting:
allow:
id: percy
.. tab:: datasette.json

.. code-block:: json
{
"allow": {
"id": [
"sharon",
"percy"
]
},
"databases": {
"accounting": {
"allow": {
"id": "percy"
}
}
}
}
.. [[[end]]]
:ref:`authentication_permissions_config` has the full details.

.. _configuration_reference_canned_queries:

Canned queries configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TODO
:ref:`Canned queries <canned_queries>` are named SQL queries that appear in the Datasette interface. They can be configured in ``datasette.yaml`` using the ``queries`` key at the database level:

.. [[[cog
from metadata_doc import config_example, config_example
config_example(cog, {
"databases": {
"sf-trees": {
"queries": {
"just_species": {
"sql": "select qSpecies from Street_Tree_List"
}
}
}
}
})
.. ]]]
.. tab:: datasette.yaml

.. code-block:: yaml
databases:
sf-trees:
queries:
just_species:
sql: select qSpecies from Street_Tree_List
.. tab:: datasette.json

.. code-block:: json
{
"databases": {
"sf-trees": {
"queries": {
"just_species": {
"sql": "select qSpecies from Street_Tree_List"
}
}
}
}
}
.. [[[end]]]
See the :ref:`canned queries documentation <canned_queries>` for more, including how to configure :ref:`writable canned queries <canned_queries_writable>`.

.. _configuration_reference_css_js:
Extra CSS and JS configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TODO
Custom CSS and JavaScript
~~~~~~~~~~~~~~~~~~~~~~~~~

Datasette can load additional CSS and JavaScript files, configured in ``datasette.yaml`` like this:

.. [[[cog
from metadata_doc import config_example
config_example(cog, """
extra_css_urls:
- https://simonwillison.net/static/css/all.bf8cd891642c.css
extra_js_urls:
- https://code.jquery.com/jquery-3.2.1.slim.min.js
""")
.. ]]]
.. tab:: datasette.yaml

.. code-block:: yaml
extra_css_urls:
- https://simonwillison.net/static/css/all.bf8cd891642c.css
extra_js_urls:
- https://code.jquery.com/jquery-3.2.1.slim.min.js
.. tab:: datasette.json

.. code-block:: json
{
"extra_css_urls": [
"https://simonwillison.net/static/css/all.bf8cd891642c.css"
],
"extra_js_urls": [
"https://code.jquery.com/jquery-3.2.1.slim.min.js"
]
}
.. [[[end]]]
The extra CSS and JavaScript files will be linked in the ``<head>`` of every page:

.. code-block:: html

<link rel="stylesheet" href="https://simonwillison.net/static/css/all.bf8cd891642c.css">
<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>

You can also specify a SRI (subresource integrity hash) for these assets:

.. [[[cog
config_example(cog, """
extra_css_urls:
- url: https://simonwillison.net/static/css/all.bf8cd891642c.css
sri: sha384-9qIZekWUyjCyDIf2YK1FRoKiPJq4PHt6tp/ulnuuyRBvazd0hG7pWbE99zvwSznI
extra_js_urls:
- url: https://code.jquery.com/jquery-3.2.1.slim.min.js
sri: sha256-k2WSCIexGzOj3Euiig+TlR8gA0EmPjuc79OEeY5L45g=
""")
.. ]]]
.. tab:: datasette.yaml

.. code-block:: yaml
extra_css_urls:
- url: https://simonwillison.net/static/css/all.bf8cd891642c.css
sri: sha384-9qIZekWUyjCyDIf2YK1FRoKiPJq4PHt6tp/ulnuuyRBvazd0hG7pWbE99zvwSznI
extra_js_urls:
- url: https://code.jquery.com/jquery-3.2.1.slim.min.js
sri: sha256-k2WSCIexGzOj3Euiig+TlR8gA0EmPjuc79OEeY5L45g=
.. tab:: datasette.json

.. code-block:: json
{
"extra_css_urls": [
{
"url": "https://simonwillison.net/static/css/all.bf8cd891642c.css",
"sri": "sha384-9qIZekWUyjCyDIf2YK1FRoKiPJq4PHt6tp/ulnuuyRBvazd0hG7pWbE99zvwSznI"
}
],
"extra_js_urls": [
{
"url": "https://code.jquery.com/jquery-3.2.1.slim.min.js",
"sri": "sha256-k2WSCIexGzOj3Euiig+TlR8gA0EmPjuc79OEeY5L45g="
}
]
}
.. [[[end]]]
This will produce:

.. code-block:: html

<link rel="stylesheet" href="https://simonwillison.net/static/css/all.bf8cd891642c.css"
integrity="sha384-9qIZekWUyjCyDIf2YK1FRoKiPJq4PHt6tp/ulnuuyRBvazd0hG7pWbE99zvwSznI"
crossorigin="anonymous">
<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"
integrity="sha256-k2WSCIexGzOj3Euiig+TlR8gA0EmPjuc79OEeY5L45g="
crossorigin="anonymous"></script>

Modern browsers will only execute the stylesheet or JavaScript if the SRI hash
matches the content served. You can generate hashes using `www.srihash.org <https://www.srihash.org/>`_

Items in ``"extra_js_urls"`` can specify ``"module": true`` if they reference JavaScript that uses `JavaScript modules <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules>`__. This configuration:

.. [[[cog
config_example(cog, """
extra_js_urls:
- url: https://example.datasette.io/module.js
module: true
""")
.. ]]]
.. tab:: datasette.yaml

.. code-block:: yaml
extra_js_urls:
- url: https://example.datasette.io/module.js
module: true
.. tab:: datasette.json

.. code-block:: json
{
"extra_js_urls": [
{
"url": "https://example.datasette.io/module.js",
"module": true
}
]
}
.. [[[end]]]
Will produce this HTML:

.. code-block:: html

<script type="module" src="https://example.datasette.io/module.js"></script>



Loading

0 comments on commit b466749

Please sign in to comment.