Updated docs renaming config to settings

- config.html is now settings.html
- ConfigOption in app.py is now Setting
- updated documentation unit tests

Refs #1106

.github/workflows/deploy-latest.yml

@@ -53,11 +53,11 @@ jobs:
             --plugins-dir=plugins \
             --branch=$GITHUB_SHA \
             --version-note=$GITHUB_SHA \
-            --extra-options="--config template_debug:1" \
+            --extra-options="--setting template_debug 1" \
             --service=datasette-latest
         # Deploy docs.db to a different service
         datasette publish cloudrun docs.db \
             --branch=$GITHUB_SHA \
             --version-note=$GITHUB_SHA \
-            --extra-options="--config template_debug:1" \
+            --extra-options="--setting template_debug 1" \
             --service=datasette-docs-latest

datasette/app.py

@@ -82,91 +82,85 @@
 
 MEMORY = object()
 
-ConfigOption = collections.namedtuple("ConfigOption", ("name", "default", "help"))
-CONFIG_OPTIONS = (
-    ConfigOption("default_page_size", 100, "Default page size for the table view"),
-    ConfigOption(
+Setting = collections.namedtuple("Setting", ("name", "default", "help"))
+SETTINGS = (
+    Setting("default_page_size", 100, "Default page size for the table view"),
+    Setting(
         "max_returned_rows",
         1000,
         "Maximum rows that can be returned from a table or custom query",
     ),
-    ConfigOption(
+    Setting(
         "num_sql_threads",
         3,
         "Number of threads in the thread pool for executing SQLite queries",
     ),
-    ConfigOption(
-        "sql_time_limit_ms", 1000, "Time limit for a SQL query in milliseconds"
-    ),
-    ConfigOption(
+    Setting("sql_time_limit_ms", 1000, "Time limit for a SQL query in milliseconds"),
+    Setting(
         "default_facet_size", 30, "Number of values to return for requested facets"
     ),
-    ConfigOption(
-        "facet_time_limit_ms", 200, "Time limit for calculating a requested facet"
-    ),
-    ConfigOption(
+    Setting("facet_time_limit_ms", 200, "Time limit for calculating a requested facet"),
+    Setting(
         "facet_suggest_time_limit_ms",
         50,
         "Time limit for calculating a suggested facet",
     ),
-    ConfigOption(
+    Setting(
         "hash_urls",
         False,
         "Include DB file contents hash in URLs, for far-future caching",
     ),
-    ConfigOption(
+    Setting(
         "allow_facet",
         True,
         "Allow users to specify columns to facet using ?_facet= parameter",
     ),
-    ConfigOption(
+    Setting(
         "allow_download",
         True,
         "Allow users to download the original SQLite database files",
     ),
-    ConfigOption("suggest_facets", True, "Calculate and display suggested facets"),
-    ConfigOption(
+    Setting("suggest_facets", True, "Calculate and display suggested facets"),
+    Setting(
         "default_cache_ttl",
         5,
         "Default HTTP cache TTL (used in Cache-Control: max-age= header)",
     ),
-    ConfigOption(
+    Setting(
         "default_cache_ttl_hashed",
         365 * 24 * 60 * 60,
         "Default HTTP cache TTL for hashed URL pages",
     ),
-    ConfigOption(
-        "cache_size_kb", 0, "SQLite cache size in KB (0 == use SQLite default)"
-    ),
-    ConfigOption(
+    Setting("cache_size_kb", 0, "SQLite cache size in KB (0 == use SQLite default)"),
+    Setting(
         "allow_csv_stream",
         True,
         "Allow .csv?_stream=1 to download all rows (ignoring max_returned_rows)",
     ),
-    ConfigOption(
+    Setting(
         "max_csv_mb",
         100,
         "Maximum size allowed for CSV export in MB - set 0 to disable this limit",
     ),
-    ConfigOption(
+    Setting(
         "truncate_cells_html",
         2048,
         "Truncate cells longer than this in HTML table view - set 0 to disable",
     ),
-    ConfigOption(
+    Setting(
         "force_https_urls",
         False,
         "Force URLs in API output to always use https:// protocol",
     ),
-    ConfigOption(
+    Setting(
         "template_debug",
         False,
         "Allow display of template debug information with ?_context=1",
     ),
-    ConfigOption("base_url", "/", "Datasette URLs should use this base path"),
+    Setting("base_url", "/", "Datasette URLs should use this base path"),
 )
 
-DEFAULT_CONFIG = {option.name: option.default for option in CONFIG_OPTIONS}
+DEFAULT_SETTINGS = {option.name: option.default for option in SETTINGS}
 
 
 async def favicon(request, send):
@@ -270,7 +264,7 @@ def __init__(
             raise StartupError("config.json should be renamed to settings.json")
         if config_dir and (config_dir / "settings.json").exists() and not config:
             config = json.load((config_dir / "settings.json").open())
-        self._config = dict(DEFAULT_CONFIG, **(config or {}))
+        self._config = dict(DEFAULT_SETTINGS, **(config or {}))
         self.renderers = {}  # File extension -> (renderer, can_render) functions
         self.version_note = version_note
         self.executor = futures.ThreadPoolExecutor(
@@ -358,7 +352,7 @@ def config(self, key):
 
     def config_dict(self):
         # Returns a fully resolved config dictionary, useful for templates
-        return {option.name: self.config(option.name) for option in CONFIG_OPTIONS}
+        return {option.name: self.config(option.name) for option in SETTINGS}
 
     def metadata(self, key=None, database=None, table=None, fallback=True):
         """

datasette/cli.py

@@ -12,7 +12,7 @@
 import sys
 from runpy import run_module
 import webbrowser
-from .app import Datasette, DEFAULT_CONFIG, CONFIG_OPTIONS, pm
+from .app import Datasette, DEFAULT_SETTINGS, SETTINGS, pm
 from .utils import (
     StartupError,
     check_connection,
@@ -39,15 +39,15 @@ def convert(self, config, param, ctx):
             self.fail(f'"{config}" should be name:value', param, ctx)
             return
         name, value = config.split(":", 1)
-        if name not in DEFAULT_CONFIG:
+        if name not in DEFAULT_SETTINGS:
             self.fail(
                 f"{name} is not a valid option (--help-config to see all)",
                 param,
                 ctx,
             )
             return
         # Type checking
-        default = DEFAULT_CONFIG[name]
+        default = DEFAULT_SETTINGS[name]
         if isinstance(default, bool):
             try:
                 return name, value_as_boolean(value)
@@ -72,15 +72,15 @@ class Setting(CompositeParamType):
 
     def convert(self, config, param, ctx):
         name, value = config
-        if name not in DEFAULT_CONFIG:
+        if name not in DEFAULT_SETTINGS:
             self.fail(
                 f"{name} is not a valid option (--help-config to see all)",
                 param,
                 ctx,
             )
             return
         # Type checking
-        default = DEFAULT_CONFIG[name]
+        default = DEFAULT_SETTINGS[name]
         if isinstance(default, bool):
             try:
                 return name, value_as_boolean(value)
@@ -432,7 +432,7 @@ def serve(
             formatter.write_dl(
                 [
                     (option.name, f"{option.help} (default={option.default})")
-                    for option in CONFIG_OPTIONS
+                    for option in SETTINGS
                 ]
             )
         click.echo(formatter.getvalue())

docs/changelog.rst

@@ -49,7 +49,7 @@ The new :ref:`internals_datasette_urls` family of methods can be used to generat
 Running Datasette behind a proxy
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :ref:`config_base_url` configuration option is designed to help run Datasette on a specific path behind a proxy - for example if you want to run an instance of Datasette at ``/my-datasette/`` within your existing site's URL hierarchy, proxied behind nginx or Apache.
+The :ref:`setting_base_url` configuration option is designed to help run Datasette on a specific path behind a proxy - for example if you want to run an instance of Datasette at ``/my-datasette/`` within your existing site's URL hierarchy, proxied behind nginx or Apache.
 
 Support for this configuration option has been greatly improved (`#1023 <https://github.com/simonw/datasette/issues/1023>`__), and guidelines for using it are now available in a new documentation section on :ref:`deploying_proxy`. (`#1027 <https://github.com/simonw/datasette/issues/1027>`__)
 
@@ -353,9 +353,9 @@ Signed values and secrets
 
 Both flash messages and user authentication needed a way to sign values and set signed cookies. Two new methods are now available for plugins to take advantage of this mechanism: :ref:`datasette_sign` and :ref:`datasette_unsign`.
 
-Datasette will generate a secret automatically when it starts up, but to avoid resetting the secret (and hence invalidating any cookies) every time the server restarts you should set your own secret. You can pass a secret to Datasette using the new ``--secret`` option or with a ``DATASETTE_SECRET`` environment variable. See :ref:`config_secret` for more details.
+Datasette will generate a secret automatically when it starts up, but to avoid resetting the secret (and hence invalidating any cookies) every time the server restarts you should set your own secret. You can pass a secret to Datasette using the new ``--secret`` option or with a ``DATASETTE_SECRET`` environment variable. See :ref:`settings_secret` for more details.
 
-You can also set a secret when you deploy Datasette using ``datasette publish`` or ``datasette package`` - see :ref:`config_publish_secrets`.
+You can also set a secret when you deploy Datasette using ``datasette publish`` or ``datasette package`` - see :ref:`settings_publish_secrets`.
 
 Plugins can now sign values and verify their signatures using the :ref:`datasette.sign() <datasette_sign>` and :ref:`datasette.unsign() <datasette_unsign>` methods.
 
@@ -450,7 +450,7 @@ A small release which provides improved internal methods for use in plugins, alo
 
 You can now create :ref:`custom pages <custom_pages>` within your Datasette instance using a custom template file. For example, adding a template file called ``templates/pages/about.html`` will result in a new page being served at ``/about`` on your instance. See the :ref:`custom pages documentation <custom_pages>` for full details, including how to return custom HTTP headers, redirects and status codes. (`#648 <https://github.com/simonw/datasette/issues/648>`__)
 
-:ref:`config_dir` (`#731 <https://github.com/simonw/datasette/issues/731>`__) allows you to define a custom Datasette instance as a directory. So instead of running the following::
+:ref:`settings_dir` (`#731 <https://github.com/simonw/datasette/issues/731>`__) allows you to define a custom Datasette instance as a directory. So instead of running the following::
 
     $ datasette one.db two.db \
       --metadata.json \
@@ -480,7 +480,7 @@ Also in this release:
 * Datasette :ref:`metadata` can now be provided as a YAML file as an optional alternative to JSON. See :ref:`metadata_yaml`. (`#713 <https://github.com/simonw/datasette/issues/713>`__)
 * Removed support for ``datasette publish now``, which used the the now-retired Zeit Now v1 hosting platform. A new plugin, `datasette-publish-now <https://github.com/simonw/datasette-publish-now>`__, can be installed to publish data to Zeit (`now Vercel <https://vercel.com/blog/zeit-is-now-vercel>`__) Now v2. (`#710 <https://github.com/simonw/datasette/issues/710>`__)
 * Fixed a bug where the ``extra_template_vars(request, view_name)`` plugin hook was not receiving the correct ``view_name``. (`#716 <https://github.com/simonw/datasette/issues/716>`__)
-* Variables added to the template context by the ``extra_template_vars()`` plugin hook are now shown in the ``?_context=1`` debugging mode (see :ref:`config_template_debug`). (`#693 <https://github.com/simonw/datasette/issues/693>`__)
+* Variables added to the template context by the ``extra_template_vars()`` plugin hook are now shown in the ``?_context=1`` debugging mode (see :ref:`settings_template_debug`). (`#693 <https://github.com/simonw/datasette/issues/693>`__)
 * Fixed a bug where the "templates considered" HTML comment was no longer being displayed. (`#689 <https://github.com/simonw/datasette/issues/689>`__)
 * Fixed a ``datasette publish`` bug where ``--plugin-secret`` would over-ride plugin configuration in the provided ``metadata.json`` file. (`#724 <https://github.com/simonw/datasette/issues/724>`__)
 * Added a new CSS class for customizing the canned query page. (`#727 <https://github.com/simonw/datasette/issues/727>`__)
@@ -490,7 +490,7 @@ Also in this release:
 0.39 (2020-03-24)
 -----------------
 
-* New :ref:`config_base_url` configuration setting for serving up the correct links while running Datasette under a different URL prefix. (`#394 <https://github.com/simonw/datasette/issues/394>`__)
+* New :ref:`setting_base_url` configuration setting for serving up the correct links while running Datasette under a different URL prefix. (`#394 <https://github.com/simonw/datasette/issues/394>`__)
 * New metadata settings ``"sort"`` and ``"sort_desc"`` for setting the default sort order for a table. See :ref:`metadata_default_sort`. (`#702 <https://github.com/simonw/datasette/issues/702>`__)
 * Sort direction arrow now displays by default on the primary key. This means you only have to click once (not twice) to sort in reverse order. (`#677 <https://github.com/simonw/datasette/issues/677>`__)
 * New ``await Request(scope, receive).post_vars()`` method for accessing POST form variables. (`#700 <https://github.com/simonw/datasette/issues/700>`__)
@@ -565,7 +565,7 @@ Also in this release:
 * asyncio task information is now included on the ``/-/threads`` debug page
 * Bumped Uvicorn dependency 0.11
 * You can now use ``--port 0`` to listen on an available port
-* New :ref:`config_template_debug` setting for debugging templates, e.g. https://latest.datasette.io/fixtures/roadside_attractions?_context=1 (`#654 <https://github.com/simonw/datasette/issues/654>`__)
+* New :ref:`settings_template_debug` setting for debugging templates, e.g. https://latest.datasette.io/fixtures/roadside_attractions?_context=1 (`#654 <https://github.com/simonw/datasette/issues/654>`__)
 
 .. _v0_32:
 
@@ -1000,7 +1000,7 @@ Check out the :ref:`CSV export documentation <csv_export>` for more details, or
 try the feature out on
 https://fivethirtyeight.datasettes.com/fivethirtyeight/bechdel%2Fmovies
 
-If your table has more than :ref:`config_max_returned_rows` (default 1,000)
+If your table has more than :ref:`settings_max_returned_rows` (default 1,000)
 Datasette provides the option to *stream all rows*. This option takes advantage
 of async Python and Datasette's efficient :ref:`pagination <pagination>` to
 iterate through the entire matching result set and stream it back as a
@@ -1020,7 +1020,7 @@ table, using the new ``_labels=on`` querystring option. See
 New configuration settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Datasette's :ref:`config` now also supports boolean settings. A number of new
+Datasette's :ref:`settings` now also supports boolean settings. A number of new
 configuration options have been added:
 
 * ``num_sql_threads`` - the number of threads used to execute SQLite queries. Defaults to 3.

docs/csv_export.rst

@@ -23,7 +23,7 @@ file, which looks like this and has the following options:
   the ``city_id`` column is accompanied by a ``city_id_label`` column.
 
 * **stream all rows** - by default CSV files only contain the first
-  :ref:`config_max_returned_rows` records. This option will cause Datasette to
+  :ref:`settings_max_returned_rows` records. This option will cause Datasette to
   loop through every matching record and return them as a single CSV file.
 
 You can try that out on https://latest.datasette.io/fixtures/facetable?_size=4
@@ -40,9 +40,9 @@ Since databases can get pretty large, by default this option is capped at 100MB
 if a table returns more than 100MB of data the last line of the CSV will be a
 truncation error message.
 
-You can increase or remove this limit using the :ref:`config_max_csv_mb` config
+You can increase or remove this limit using the :ref:`settings_max_csv_mb` config
 setting. You can also disable the CSV export feature entirely using
-:ref:`config_allow_csv_stream`.
+:ref:`settings_allow_csv_stream`.
 
 A note on URLs
 --------------

docs/deploying.rst

@@ -58,7 +58,7 @@ Add a random value for the ``DATASETTE_SECRET`` - this will be used to sign Data
 
     $ python3 -c 'import secrets; print(secrets.token_hex(32))'
 
-This configuration will run Datasette against all database files contained in the ``/home/ubunt/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.
+This configuration will run Datasette against all database files contained in the ``/home/ubunt/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:`settings_dir` for details.
 
 You can start the Datasette process running using the following::
 
@@ -101,7 +101,7 @@ The ``Procfile`` lets the hosting platform know how to run the command that serv
 
     web: datasette . -h 0.0.0.0 -p $PORT --cors
 
-The ``$PORT`` environment variable is provided by the hosting platform. ``--cors`` enables CORS requests from JavaScript running on other websites to your domain - omit this if you don't want to allow CORS. You can add additional Datasette :ref:`config` options here too.
+The ``$PORT`` environment variable is provided by the hosting platform. ``--cors`` enables CORS requests from JavaScript running on other websites to your domain - omit this if you don't want to allow CORS. You can add additional Datasette :ref:`settings` options here too.
 
 These two files should be enough to deploy Datasette on any host that supports buildpacks. Datasette will serve any SQLite files that are included in the root directory of the application.
 
@@ -118,9 +118,9 @@ Running Datasette behind a proxy
 
 You may wish to run Datasette behind an Apache or nginx proxy, using a path within your existing site.
 
-You can use the :ref:`config_base_url` configuration setting to tell Datasette to serve traffic with a specific URL prefix. For example, you could run Datasette like this::
+You can use the :ref:`setting_base_url` configuration setting to tell Datasette to serve traffic with a specific URL prefix. For example, you could run Datasette like this::
 
-    datasette my-database.db --config base_url:/my-datasette/ -p 8009
+    datasette my-database.db --setting base_url /my-datasette/ -p 8009
 
 This will run Datasette with the following URLs:
 

docs/index.rst

@@ -51,7 +51,7 @@ Contents
    full_text_search
    spatialite
    metadata
-   config
+   settings
    introspection
    custom_templates
    plugins