From 9af2964f6fd4ae876ef8ecd2c14c2ffa61542fdb Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Thu, 7 Dec 2017 09:19:35 -0800
Subject: [PATCH] Documentation for metadata.json and "datasette skeleton"
 command

http://datasette.readthedocs.io/en/latest/metadata.html

Closes #166
---
 docs/index.rst    |   1 +
 docs/metadata.rst | 104 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 docs/metadata.rst

diff --git a/docs/index.rst b/docs/index.rst
index ae19800c..4b58461f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,6 +18,7 @@ Contents
 
    getting_started
    sql_queries
+   metadata
    custom_templates
    changelog
 
diff --git a/docs/metadata.rst b/docs/metadata.rst
new file mode 100644
index 00000000..aa002ff7
--- /dev/null
+++ b/docs/metadata.rst
@@ -0,0 +1,104 @@
+Metadata
+========
+
+Data loves metadata. Any time you run Datasette you can optionally include a
+JSON file with metadata about your databases and tables. Datasette will then
+display that information in the web UI.
+
+Run Datasette like this::
+
+    datasette database1.db database2.db --metadata metadata.json
+
+Your ``metadata.json`` file can look something like this::
+
+    {
+        "title": "Custom title for your index page",
+        "description": "Some description text can go here",
+        "license": "ODbL",
+        "license_url": "https://opendatacommons.org/licenses/odbl/",
+        "source": "Original Data Source",
+        "source_url": "http://example.com/"
+    }
+
+The above metadata will be displayed on the index page of your Datasette-powered
+site. The source and license information will also be included in the footer of
+every page served by Datasette.
+
+Any special HTML characters in ``description`` will be escaped. If you want to
+include HTML in your description, you can use a ``description_html`` property
+instead.
+
+Per-database and per-table metadata
+-----------------------------------
+
+Metadata at the top level of the JSON will be shown on the index page and in the
+footer on every page of the site. The license and source is expected to apply to
+all of your data.
+
+You can also provide metadata at the per-database or per-table level, like this::
+
+    {
+        "databases": {
+            "database1": {
+                "source": "Alternative source",
+                "source_url": "http://example.com/",
+                "tables": {
+                    "example_table": {
+                        "description_html": "Custom <em>table</em> description",
+                        "license": "CC BY 3.0 US",
+                        "license_url": "https://creativecommons.org/licenses/by/3.0/us/"
+                    }
+                }
+            }
+        }
+    }
+
+Each of the top-level metadata fields can be used at the database and table level.
+
+Generating a metadata skeleton
+------------------------------
+
+Tracking down the names of all of your databases and tables and formatting them
+as JSON can be a little tedious, so Datasette provides a tool to help you
+generate a "skeleton" JSON file::
+
+    datasette skeleton database1.db database2.db
+
+This will create a ``metadata.json`` file looking something like this::
+
+    {
+        "title": null,
+        "description": null,
+        "description_html": null,
+        "license": null,
+        "license_url": null,
+        "source": null,
+        "source_url": null,
+        "databases": {
+            "database1": {
+                "title": null,
+                "description": null,
+                "description_html": null,
+                "license": null,
+                "license_url": null,
+                "source": null,
+                "source_url": null,
+                "queries": {},
+                "tables": {
+                    "example_table": {
+                        "title": null,
+                        "description": null,
+                        "description_html": null,
+                        "license": null,
+                        "license_url": null,
+                        "source": null,
+                        "source_url": null
+                    }
+                }
+            },
+            "database2": ...
+        }
+    }
+
+You can replace any of the ``null`` values with a JSON string to populate that
+piece of metadata.