Add documentation

Author: evansd

docs/reference/language.md

@@ -130,6 +130,8 @@ other) groupings.
 
 ---8<-- 'includes/generated_docs/language__measures.md'
 
+---
+
 
 ## Parameters
 
@@ -139,3 +141,10 @@ from the [command line](cli.md#generate-dataset.user_args).
 ---8<-- 'includes/generated_docs/language__parameters.md'
 
 ---
+
+
+## Permissions
+
+---8<-- 'includes/generated_docs/language__permissions.md'
+
+---

ehrql/docs/language.py

@@ -110,6 +110,9 @@ def build_language():
         "parameters": {
             "get_parameter": namespace["get_parameter"],
         },
+        "permissions": {
+            "claim_permissions": namespace["claim_permissions"],
+        },
     }
 
     # Check that the documentation is complete

ehrql/permissions.py

@@ -16,6 +16,24 @@ class EHRQLPermissionError(Exception):
 
 
 def claim_permissions(*permissions):
+    """
+    Some tables and features in ehrQL can only be accessed with specific permission set
+    by the OpenSAFELY team. These restrictions are only enforced when working with real
+    data, however to avoid confusion we also check them when working with dummy data.
+
+    When using dummy data you can grant yourself any permission using the
+    `claim_permissions()` function. For example:
+
+        from ehrql import claim_permissions
+
+        claim_permissions("some_permission", "another_permission")
+
+    This can go anywhere in your dataset or measure definition file.
+
+    This will allow you to develop your ehrQL code locally. But please **note that you
+    will only be able to run against real data if you have had the necessary permissions
+    granted by the OpenSAFELY team**.
+    """
     for permission in permissions:
         # Use dictionary as convenient ordered set
         CLAIMED_PERMISSIONS[permission] = True

tests/unit/test_docs.py

@@ -56,6 +56,7 @@ def test_render(tmp_path):
         "language__functions.md",
         "language__measures.md",
         "language__parameters.md",
+        "language__permissions.md",
         "language__series.md",
         "schemas",
         "schemas.md",