From 42f4851e3e7885f1092f104d6c883cea40b12f02 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Sat, 24 Oct 2020 18:17:30 -0700
Subject: [PATCH] Documentation for .absolute_url(request, path), refs #1034

---
 docs/config.rst    |  1 +
 docs/internals.rst | 20 ++++++++++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/docs/config.rst b/docs/config.rst
index ff39f02a..0883e532 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -220,6 +220,7 @@ HTML page. Set this to 0 to disable truncation.
 
     datasette mydatabase.db --config truncate_cells_html:0
 
+.. _config_force_https_urls:
 
 force_https_urls
 ~~~~~~~~~~~~~~~~
diff --git a/docs/internals.rst b/docs/internals.rst
index 1c714eb8..4ebeb983 100644
--- a/docs/internals.rst
+++ b/docs/internals.rst
@@ -332,6 +332,26 @@ Datasette's flash messaging mechanism allows you to add a message that will be d
 
 You can try out these messages (including the different visual styling of the three message types) using the ``/-/messages`` debugging tool.
 
+.. _datasette_absolute_url:
+
+.absolute_url(request, path)
+----------------------------
+
+``request`` - Request
+    The current Request object
+
+``path`` - string
+    A path, for example ``/dbname/table.json``
+
+Returns the absolute URL for the given path, including the protocol and host. For example:
+
+.. code-block:: python
+
+    absolute_url = datasette.absolute_url(request, "/dbname/table.json")
+    # Would return "http://localhost:8001/dbname/table.json"
+
+The current request object is used to determine the hostname and protocol that should be used for the returned URL. The :ref:`config_force_https_urls` configuration setting is taken into account.
+
 .. _internals_datasette_client:
 
 datasette.client