JSON/YAML tabs on configuration docs page

simonw · Sep 13, 2023 · 16f0b6d · 16f0b6d
1 parent b2ec871
commit 16f0b6d
Showing 1 changed file with 171 additions and 0 deletions.
diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -18,6 +18,40 @@ To facilitate this, You can provide a ``datasette.yaml`` configuration file to d
 
 Here's a full example of all the valid configuration options that can exist inside ``datasette.yaml``.
 
+.. [[[cog
+    from metadata_doc import metadata_example
+    import textwrap
+    metadata_example(cog, yaml=textwrap.dedent(
+      """
+        # Datasette settings block
+        settings:
+          default_page_size: 50
+          sql_time_limit_ms: 3500
+          max_returned_rows: 2000
+
+        # top-level plugin configuration
+        plugins:
+          datasette-my-plugin:
+            key: valueA
+
+        # Database and table-level configuration
+        databases:
+          your_db_name:
+            # plugin configuration for the your_db_name database
+            plugins:
+              datasette-my-plugin:
+                key: valueA
+            tables:
+              your_table_name:
+                # plugin configuration for the your_table_name table
+                # inside your_db_name database
+                plugins:
+                  datasette-my-plugin:
+                    key: valueB
+        """)
+      )
+.. ]]]
+
 .. tab:: YAML
 
     .. code-block:: yaml
@@ -48,12 +82,61 @@ Here's a full example of all the valid configuration options that can exist insi
                   datasette-my-plugin:
                     key: valueB
 
+.. tab:: JSON
+
+    .. code-block:: json
+
+        {
+          "settings": {
+            "default_page_size": 50,
+            "sql_time_limit_ms": 3500,
+            "max_returned_rows": 2000
+          },
+          "plugins": {
+            "datasette-my-plugin": {
+              "key": "valueA"
+            }
+          },
+          "databases": {
+            "your_db_name": {
+              "plugins": {
+                "datasette-my-plugin": {
+                  "key": "valueA"
+                }
+              },
+              "tables": {
+                "your_table_name": {
+                  "plugins": {
+                    "datasette-my-plugin": {
+                      "key": "valueB"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+.. [[[end]]]
+
 .. _configuration_reference_settings:
 Settings configuration
 ~~~~~~~~~~~~~~~~~~~~~~
 
 :ref:`settings` can be configured in ``datasette.yaml`` with the ``settings`` key.
 
+.. [[[cog
+    from metadata_doc import metadata_example
+    import textwrap
+    metadata_example(cog, yaml=textwrap.dedent(
+      """
+        # inside datasette.yaml
+        settings:
+           default_allow_sql: off
+           default_page_size: 50
+        """).strip()
+      )
+.. ]]]
+
 .. tab:: YAML
 
     .. code-block:: yaml
@@ -63,13 +146,37 @@ Settings configuration
            default_allow_sql: off
            default_page_size: 50
 
+.. tab:: JSON
+
+    .. code-block:: json
+
+        {
+          "settings": {
+            "default_allow_sql": "off",
+            "default_page_size": 50
+          }
+        }
+.. [[[end]]]
 
 .. _configuration_reference_plugins:
 Plugin configuration
 ~~~~~~~~~~~~~~~~~~~~
 
 Configuration for plugins can be defined inside ``datasette.yaml``. For top-level plugin configuration, use the ``plugins`` key.
 
+.. [[[cog
+    from metadata_doc import metadata_example
+    import textwrap
+    metadata_example(cog, yaml=textwrap.dedent(
+      """
+        # inside datasette.yaml
+        plugins:
+          datasette-my-plugin:
+            key: my_value
+        """).strip()
+      )
+.. ]]]
+
 .. tab:: YAML
 
     .. code-block:: yaml
@@ -79,8 +186,44 @@ Configuration for plugins can be defined inside ``datasette.yaml``. For top-leve
           datasette-my-plugin:
             key: my_value
 
+.. tab:: JSON
+
+    .. code-block:: json
+
+        {
+          "plugins": {
+            "datasette-my-plugin": {
+              "key": "my_value"
+            }
+          }
+        }
+.. [[[end]]]
+
 For database level or table level plugin configuration, nest it under the appropriate place under ``databases``.
 
+.. [[[cog
+    from metadata_doc import metadata_example
+    import textwrap
+    metadata_example(cog, yaml=textwrap.dedent(
+      """
+        # inside datasette.yaml
+        databases:
+          my_database:
+            # plugin configuration for the my_database database
+            plugins:
+              datasette-my-plugin:
+                key: my_value
+          my_other_database:
+            tables:
+              my_table:
+                # plugin configuration for the my_table table inside the my_other_database database
+                plugins:
+                  datasette-my-plugin:
+                    key: my_value
+      """).strip()
+      )
+.. ]]]
+
 .. tab:: YAML
 
     .. code-block:: yaml
@@ -99,3 +242,31 @@ For database level or table level plugin configuration, nest it under the approp
                 plugins:
                   datasette-my-plugin:
                     key: my_value
+
+.. tab:: JSON
+
+    .. code-block:: json
+
+        {
+          "databases": {
+            "my_database": {
+              "plugins": {
+                "datasette-my-plugin": {
+                  "key": "my_value"
+                }
+              }
+            },
+            "my_other_database": {
+              "tables": {
+                "my_table": {
+                  "plugins": {
+                    "datasette-my-plugin": {
+                      "key": "my_value"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+.. [[[end]]]