Docs for IndexView, TableView, RowView, closes #299

Also removed xfail from test_view_classes_are_documented, so any future *View
classes that are added without documentation will cause the tests to fail.

docs/config.rst

@@ -103,6 +103,8 @@ Should users be able to download the original SQLite database using a link on th
 
     datasette mydatabase.db --config allow_download:off
 
+.. _config_allow_sql:
+
 allow_sql
 ---------
 

docs/index.rst

@@ -18,6 +18,7 @@ Contents
 
    installation
    getting_started
+   pages
    publish
    json_api
    sql_queries

docs/json_api.rst

@@ -164,6 +164,8 @@ querystring arguments:
     For how many seconds should this response be cached by HTTP proxies? Use
     ``?_ttl=0`` to disable HTTP caching entirely for this request.
 
+.. _table_arguments:
+
 Special table arguments
 -----------------------
 

docs/pages.rst

@@ -0,0 +1,86 @@
+.. _pages:
+
+=========================
+ Pages and API endpoints
+=========================
+
+The Datasette web application offers a number of different pages that can be accessed to explore the data in question, each of which is accompanied by an equivalent JSON API.
+
+.. _IndexView:
+
+Top-level index
+===============
+
+The root page of any Datasette installation is an index page that lists all of the currently attached databases. Some examples:
+
+* `fivethirtyeight.datasettes.com <https://fivethirtyeight.datasettes.com/>`_
+* `global-power-plants.datasettes.com <https://global-power-plants.datasettes.com/>`_
+* `register-of-members-interests.datasettes.com <https://register-of-members-interests.datasettes.com/>`_
+
+Add ``/.json`` to the end of the URL for the JSON version of the underlying data:
+
+* `fivethirtyeight.datasettes.com/.json <https://fivethirtyeight.datasettes.com/.json>`_
+* `global-power-plants.datasettes.com/.json <https://global-power-plants.datasettes.com/.json>`_
+* `register-of-members-interests.datasettes.com/.json <https://register-of-members-interests.datasettes.com/.json>`_
+
+.. _DatabaseView:
+
+Database
+========
+
+Each database has a page listing the tables, views and canned queries
+available for that database. If the :ref:`config_allow_sql` config option is enabled (it's turned on by default) there will also be an interface for executing arbitrary SQL select queries against the data.
+
+Examples:
+
+* `fivethirtyeight.datasettes.com/fivethirtyeight-ac35616 <https://fivethirtyeight.datasettes.com/fivethirtyeight-ac35616>`_
+* `global-power-plants.datasettes.com/global-power-plants-9e55be2 <https://global-power-plants.datasettes.com/global-power-plants-9e55be2>`_
+
+The JSON version of this page provides programmatic access to the underlying data:
+
+* `fivethirtyeight.datasettes.com/fivethirtyeight-ac35616.json <https://fivethirtyeight.datasettes.com/fivethirtyeight-ac35616.json>`_
+* `global-power-plants.datasettes.com/global-power-plants-9e55be2.json <https://global-power-plants.datasettes.com/global-power-plants-9e55be2.json>`_
+
+Note that these URLs end in a 7 character hash. This hash is derived from the contents of the database, and ensures that each URL is immutable: the data returned from a URL containing the hash will always be the same, since if the contents of the database file changes by even a single byte a new hash will be generated.
+
+If you access one of these URLs with an incorrect hash (say because a new version of the underlying database has been published) Datasette will 302 redirect you to the correct URL. This happens for all URLs below the database page as well.
+
+Thanks to this hashing scheme, Datasette URLs can all be returned with far-future cache expiry headers. This means browsers will cache the data (including data from the JSON APIs) for a long time, and CDNs such as `Cloudflare <https://www.cloudflare.com/>`_ or `Fastly <https://www.cloudflare.com/>`_ can be used to dramatically improve the performance of a Datasette hosted API.
+
+.. _TableView:
+
+Table
+=====
+
+The table page is the heart of Datasette: it allows users to interactively explore the contents of a database table, including sorting, filtering, :ref:`full_text_search` and applying :ref:`facets`.
+
+The HTML interface is worth spending some time exploring. As with other pages, you can return the JSON data by appending ``.json`` to the URL path, before any `?` querystring arguments.
+
+The querystring arguments are described in more detail here: :ref:`table_arguments`
+
+You can also use the table page to interactively construct a SQL query - by applying different filters and a sort order for example - and then click the "View and edit SQL" link to see the SQL query that was used for the page and edit and re-submit it.
+
+Some examples:
+
+* `../items <https://register-of-members-interests.datasettes.com/regmem-d22c12c/items>`_ lists all of the line-items registered by UK MPs as potential conflicts of interest. It demonstrates Datasette's support for :ref:`full_text_search`.
+* `../antiquities-act%2Factions_under_antiquities_act <https://fivethirtyeight.datasettes.com/fivethirtyeight-ac35616/antiquities-act%2Factions_under_antiquities_act>`_ is an interface for exploring the "actions under the antiquities act" data table published by FiveThirtyEight.
+* `../global-power-plants?country_long=United+Kingdom&fuel1=Gas <https://global-power-plants.datasettes.com/global-power-plants-9e55be2/global-power-plants?country_long=United+Kingdom&fuel1=Gas>`_ is a filtered table page showing every Gas power plant in the United Kingdom. It includes some default facets (configured using `its metadata.json <https://global-power-plants.datasettes.com/-/metadata>`_) and uses the `datasette-cluster-map <https://github.com/simonw/datasette-cluster-map>`_ plugin to show a map of the results.
+
+.. _RowView:
+
+Row
+===
+
+Every row in every Datasette table has its own URL. This means individual records can be linked to directly.
+
+Table cells with extremely long text contents are truncated on the table view according to the :ref:`config_truncate_cells_html` setting. If a cell has been truncated the full length version of that cell will be available on the row page.
+
+Rows which are the targets of foreign key references from other tables will show a link to a filtered search for all records that reference that row. Here's an example from the Registers of Members Interests database:
+
+`../people/uk.org.publicwhip%2Fperson%2F10001 <https://register-of-members-interests.datasettes.com/regmem-d22c12c/people/uk.org.publicwhip%2Fperson%2F10001>`_
+
+Note that this URL includes the encoded primary key of the record.
+
+Here's that same page as JSON:
+
+`../people/uk.org.publicwhip%2Fperson%2F10001.json <https://register-of-members-interests.datasettes.com/regmem-d22c12c/people/uk.org.publicwhip%2Fperson%2F10001.json>`_

docs/sql_queries.rst

@@ -9,9 +9,12 @@ worry about SQL injection attacks.
 The easiest way to execute custom SQL against Datasette is through the web UI.
 The database index page includes a SQL editor that lets you run any SELECT query
 you like. You can also construct queries using the filter interface on the
-tables page, then click "View and edit SQL" to open that query in the cgustom
+tables page, then click "View and edit SQL" to open that query in the custom
 SQL editor.
 
+Note that this interface is only available if the :ref:`config_allow_sql` option
+has not been disabled.
+
 Any Datasette SQL query is reflected in the URL of the page, allowing you to
 bookmark them, share them with others and navigate through previous queries
 using your browser back button.

tests/test_docs.py

@@ -68,7 +68,6 @@ def documented_views():
     return view_labels
 
 
-@pytest.mark.xfail
 @pytest.mark.parametrize("view_class", [v for v in dir(app) if v.endswith("View")])
 def test_view_classes_are_documented(documented_views, view_class):
     assert view_class in documented_views