From d1f7a275d155882ec88accba8f4e978b941caa05 Mon Sep 17 00:00:00 2001 From: Bart Feenstra Date: Tue, 16 Jan 2024 17:20:43 +0000 Subject: [PATCH] Add JSON examples to the documentation site. --- documentation/conf.py | 1 + .../usage/extension/cotton_candy.rst | 73 ++++++++++++++----- documentation/usage/extension/deriver.rst | 17 ++++- documentation/usage/extension/gramps.rst | 50 ++++++++++--- .../usage/extension/http_api_doc.rst | 17 ++++- documentation/usage/extension/maps.rst | 17 ++++- documentation/usage/extension/nginx.rst | 45 +++++++++--- documentation/usage/extension/privatizer.rst | 17 ++++- documentation/usage/extension/trees.rst | 17 ++++- documentation/usage/extension/wikipedia.rst | 17 ++++- documentation/usage/project/configuration.rst | 72 ++++++++++++------ pyproject.toml | 1 + 12 files changed, 269 insertions(+), 75 deletions(-) diff --git a/documentation/conf.py b/documentation/conf.py index 5ca463303..51348fc64 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -47,6 +47,7 @@ 'sphinx.ext.viewcode', 'sphinx_autodoc_typehints', 'sphinx_design', + 'sphinx_tabs.tabs', ] nitpicky = True modindex_common_prefix = ['betty.'] diff --git a/documentation/usage/extension/cotton_candy.rst b/documentation/usage/extension/cotton_candy.rst index 78eaab34a..24c7c89e9 100644 --- a/documentation/usage/extension/cotton_candy.rst +++ b/documentation/usage/extension/cotton_candy.rst @@ -4,29 +4,68 @@ The :py:class:`betty.extension.CottonCandy` extension provides Betty's default t Enable this extension through Betty Desktop, or in your project's :doc:`configuration file ` as follows: -.. code-block:: yaml +.. tabs:: + .. tab:: YAML + .. code-block:: yaml - extensions: - betty.extension.CottonCandy: {} + extensions: + betty.extension.CottonCandy: {} + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.CottonCandy": {} + } + } Configuration ------------- This extension is configurable through Betty Desktop or in the configuration file: -.. code-block:: yaml - - extensions: - betty.extension.CottonCandy: - configuration: - primary_inactive_color: '#ffc0cb' - primary_active_color: '#ff69b4' - link_inactive_color: '#149988' - link_active_color: '#2a615a' - featured_entities: - - entity_type: Person - entity_id: P123 - - entity_type: Place - entity_id: Amsterdam +.. tabs:: + .. tab:: YAML + .. code-block:: yaml + + extensions: + betty.extension.CottonCandy: + configuration: + primary_inactive_color: '#ffc0cb' + primary_active_color: '#ff69b4' + link_inactive_color: '#149988' + link_active_color: '#2a615a' + featured_entities: + - entity_type: Person + entity_id: P123 + - entity_type: Place + entity_id: Amsterdam + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.CottonCandy": { + "configuration" : { + "primary_inactive_color": "#ffc0cb", + "primary_active_color": "#ff69b4", + "link_inactive_color": "#149988", + "link_active_color": "#2a615a", + "featured_entities": [ + { + "entity_type": "Person", + "entity_id": "P123" + }, + { + "entity_type": "Place", + "entity_id": "Amsterdam" + } + ] + } + } + } + } All configuration options ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/documentation/usage/extension/deriver.rst b/documentation/usage/extension/deriver.rst index e6a183e3b..718f4d361 100644 --- a/documentation/usage/extension/deriver.rst +++ b/documentation/usage/extension/deriver.rst @@ -11,10 +11,21 @@ the event types used within your site as well as the existing events for each pe Enable this extension through Betty Desktop, or in your project's :doc:`configuration file ` as follows: -.. code-block:: yaml +.. tabs:: + .. tab:: YAML + .. code-block:: yaml - extensions: - betty.extension.Deriver: {} + extensions: + betty.extension.Deriver: {} + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.Deriver": {} + } + } Configuration ------------- diff --git a/documentation/usage/extension/gramps.rst b/documentation/usage/extension/gramps.rst index d0acfe9cc..a17989f35 100644 --- a/documentation/usage/extension/gramps.rst +++ b/documentation/usage/extension/gramps.rst @@ -4,22 +4,52 @@ The :py:class:`betty.extension.Gramps` extension loads entities from `Gramps ` as follows: -.. code-block:: yaml +.. tabs:: + .. tab:: YAML + .. code-block:: yaml - extensions: - betty.extension.Gramps: {} + extensions: + betty.extension.Gramps: {} + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.Gramps": {} + } + } Configuration ------------- This extension is configurable through Betty Desktop or in the configuration file: -.. code-block:: yaml - - extensions: - betty.extension.Gramps: - configuration: - family_trees: - - file: ./gramps.gpkg +.. tabs:: + .. tab:: YAML + .. code-block:: yaml + + extensions: + betty.extension.Gramps: + configuration: + family_trees: + - file: ./gramps.gpkg + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.Gramps": { + "configuration" : { + "family_trees": [ + { + "file": "./gramps.gpkg" + } + ] + } + } + } + } All configuration options diff --git a/documentation/usage/extension/http_api_doc.rst b/documentation/usage/extension/http_api_doc.rst index 14058b0fa..9a29eb18d 100644 --- a/documentation/usage/extension/http_api_doc.rst +++ b/documentation/usage/extension/http_api_doc.rst @@ -5,10 +5,21 @@ The :py:class:`betty.extension.HttpApiDoc` extension renders interactive and use Enable this extension through Betty Desktop, or in your project's :doc:`configuration file ` as follows: -.. code-block:: yaml +.. tabs:: + .. tab:: YAML + .. code-block:: yaml - extensions: - betty.extension.HttpApiDoc: {} + extensions: + betty.extension.HttpApiDoc: {} + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.HttpApiDoc": {} + } + } Configuration ------------- diff --git a/documentation/usage/extension/maps.rst b/documentation/usage/extension/maps.rst index f4696897b..65941dee5 100644 --- a/documentation/usage/extension/maps.rst +++ b/documentation/usage/extension/maps.rst @@ -5,10 +5,21 @@ The :py:class:`betty.extension.Maps` extension renders interactive maps using `L Enable this extension through Betty Desktop, or in your project's :doc:`configuration file ` as follows: -.. code-block:: yaml +.. tabs:: + .. tab:: YAML + .. code-block:: yaml - extensions: - betty.extension.Maps: {} + extensions: + betty.extension.Maps: {} + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.Maps": {} + } + } Configuration ------------- diff --git a/documentation/usage/extension/nginx.rst b/documentation/usage/extension/nginx.rst index 37194a500..98d955b81 100644 --- a/documentation/usage/extension/nginx.rst +++ b/documentation/usage/extension/nginx.rst @@ -10,22 +10,49 @@ automatically when using the ``Dockerfile``. Enable this extension through Betty Desktop, or in your project's :doc:`configuration file ` as follows: -.. code-block:: yaml +.. tabs:: + .. tab:: YAML + .. code-block:: yaml - extensions: - betty.extension.Nginx: {} + extensions: + betty.extension.Nginx: {} + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.Nginx": {} + } + } Configuration ------------- This extension is configurable through Betty Desktop or in the configuration file: -.. code-block:: yaml +.. tabs:: + .. tab:: YAML + .. code-block:: yaml - extensions: - betty.extension.Nginx: - configuration: - www_directory_path: /var/www/betty - https: true + extensions: + betty.extension.Nginx: + configuration: + www_directory_path: /var/www/betty + https: true + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.Nginx": { + "configuration" : { + "www_directory_path": "/var/www/betty", + "https": true, + } + } + } + } All configuration options ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/documentation/usage/extension/privatizer.rst b/documentation/usage/extension/privatizer.rst index e07a6467d..a1cc5d8d3 100644 --- a/documentation/usage/extension/privatizer.rst +++ b/documentation/usage/extension/privatizer.rst @@ -45,10 +45,21 @@ Source Enable this extension through Betty Desktop, or in your project's :doc:`configuration file ` as follows: -.. code-block:: yaml +.. tabs:: + .. tab:: YAML + .. code-block:: yaml - extensions: - betty.extension.Privatizer: {} + extensions: + betty.extension.Privatizer: {} + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.Privatizer": {} + } + } Configuration ------------- diff --git a/documentation/usage/extension/trees.rst b/documentation/usage/extension/trees.rst index f3ec7224a..5711900a4 100644 --- a/documentation/usage/extension/trees.rst +++ b/documentation/usage/extension/trees.rst @@ -4,10 +4,21 @@ The :py:class:`betty.extension.Trees` extension renders interactive family trees Enable this extension through Betty Desktop, or in your project's :doc:`configuration file ` as follows: -.. code-block:: yaml +.. tabs:: + .. tab:: YAML + .. code-block:: yaml - extensions: - betty.extension.Trees: {} + extensions: + betty.extension.Trees: {} + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.Trees": {} + } + } Configuration ------------- diff --git a/documentation/usage/extension/wikipedia.rst b/documentation/usage/extension/wikipedia.rst index fa06ac345..4e1a583f7 100644 --- a/documentation/usage/extension/wikipedia.rst +++ b/documentation/usage/extension/wikipedia.rst @@ -6,10 +6,21 @@ render them on the entity's page. Enable this extension through Betty Desktop, or in your project's :doc:`configuration file ` as follows: -.. code-block:: yaml +.. tabs:: + .. tab:: YAML + .. code-block:: yaml - extensions: - betty.extension.Wikipedia: {} + extensions: + betty.extension.Wikipedia: {} + + .. tab:: JSON + .. code-block:: json + + { + "extensions": { + "betty.extension.Wikipedia": {} + } + } Configuration ------------- diff --git a/documentation/usage/project/configuration.rst b/documentation/usage/project/configuration.rst index 89d1a68a3..005bb6755 100644 --- a/documentation/usage/project/configuration.rst +++ b/documentation/usage/project/configuration.rst @@ -3,27 +3,57 @@ Project configuration Project configuration files are written in YAML (``betty.yaml`` or ``betty.yml``) or JSON (``betty.json``) and are placed in the root of the project directory. Both YAML and JSON files follow the exact same -structure. An example YAML configuration: - -.. code-block:: yaml - - base_url: https://ancestry.example.com - debug: true - root_path: /betty - clean_urls: true - title: Betty's ancestry - author: Bart Feenstra - lifetime_threshold: 125 - locales: - en-US: - alias: en - nl: {} - entity_types: - Person: - generate_html_list: true - File: - generate_html_list: false - extensions: {} +structure. Example configuration: + +.. tabs:: + .. tab:: YAML + .. code-block:: yaml + + base_url: https://ancestry.example.com + debug: true + root_path: /betty + clean_urls: true + title: Betty's ancestry + author: Bart Feenstra + lifetime_threshold: 125 + locales: + en-US: + alias: en + nl: {} + entity_types: + Person: + generate_html_list: true + File: + generate_html_list: false + extensions: {} + + .. tab:: JSON + .. code-block:: json + + { + "base_url" : "https://ancestry.example.com", + "debug" : true, + "root_path" : "/betty", + "clean_urls" : true, + "title": "Betty's ancestry", + "author": "Bart Feenstra", + "lifetime_threshold": 125, + "locales": { + "en-US": { + "alias": "en" + }, + "nl": {} + }, + "entity_types": { + "Person": { + "generate_html_list": true + }, + "File": { + "generate_html_list": false + } + }, + "extensions": {} + } All configuration options ------------------------- diff --git a/pyproject.toml b/pyproject.toml index 26416b162..3c8a31f28 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,6 +37,7 @@ dependencies = [ 'reactives ~= 0.5, >= 0.5.1', 'sphinx ~= 7.2.6', 'sphinx-design ~= 0.5.0', + 'sphinx-tabs ~= 3.4.4', 'sphinx_rtd_theme ~= 2.0.0', 'sphinx-autodoc-typehints ~= 1.25.2', ]