From 5e43fe42d500a9b97b1fa3a02f90036001cbd42f Mon Sep 17 00:00:00 2001 From: Bart Feenstra Date: Fri, 9 Feb 2024 00:26:22 +0000 Subject: [PATCH] Use the sphinx-immaterial for the documentation site. (#1258) --- documentation/about.rst | 9 ++++----- documentation/about/license.rst | 2 +- documentation/conf.py | 12 ++---------- documentation/development.rst | 2 +- documentation/development/extension.rst | 11 +++++++---- documentation/usage/ancestry.rst | 9 ++++++--- documentation/usage/extension/cotton_candy.rst | 18 ++++++++++++------ documentation/usage/extension/deriver.rst | 9 ++++++--- documentation/usage/extension/gramps.rst | 18 ++++++++++++------ documentation/usage/extension/http_api_doc.rst | 9 ++++++--- documentation/usage/extension/maps.rst | 9 ++++++--- documentation/usage/extension/nginx.rst | 15 +++++++++------ documentation/usage/extension/privatizer.rst | 9 ++++++--- documentation/usage/extension/trees.rst | 9 ++++++--- documentation/usage/extension/wikipedia.rst | 9 ++++++--- documentation/usage/project.rst | 2 +- documentation/usage/project/configuration.rst | 9 ++++++--- pyproject.toml | 3 +-- 18 files changed, 98 insertions(+), 66 deletions(-) diff --git a/documentation/about.rst b/documentation/about.rst index ca8dbe463..a245f0913 100644 --- a/documentation/about.rst +++ b/documentation/about.rst @@ -31,7 +31,7 @@ Security and maintenance ^^^^^^^^^^^^^^^^^^^^^^^^ A Betty site is secure and requires almost no maintenance. -.. note:: +.. important:: This is about generated sites. You are still advised to install updates to your installation of Betty when they become available. What is Betty not? @@ -41,10 +41,9 @@ Betty does not help you gather or manage the data for your family history. For t Find Betty on ------------- -- :fab:`twitter` `Twitter `_ -- :fab:`x-twitter` `X `_ -- :fab:`github` `Github `_ -- :fab:`python` `PyPI `_ +- :si-icon:`fontawesome/brands/twitter` `Twitter `_ +- :si-icon:`fontawesome/brands/github` `Github `_ +- :si-icon:`fontawesome/brands/python` `PyPI `_ In this section --------------- diff --git a/documentation/about/license.rst b/documentation/about/license.rst index 9c5f60a6b..43486b2f7 100644 --- a/documentation/about/license.rst +++ b/documentation/about/license.rst @@ -9,7 +9,7 @@ Betty is copyright Bart Feenstra and contributors, and released under the **GPL* GNU General Public License, Version 3 ------------------------------------- -.. note:: +.. seealso:: `Read more `_ about the **GNU General Public License, Version 3** (also known as the **GPL**). The following is a verbatim copy of the license. diff --git a/documentation/conf.py b/documentation/conf.py index a302ed361..be2f8db89 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -35,15 +35,7 @@ 'conf_py_path': '/documentation/', 'betty_replacements': betty_replacements, } -html_theme = 'sphinx_rtd_theme' -html_theme_options = { - 'collapse_navigation': True, - 'sticky_navigation': True, - 'prev_next_buttons_location': None, -} -html_css_files = [ - 'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css', -] +html_theme = 'sphinx_immaterial' highlight_language = 'none' templates_path = ['_templates'] extensions = [ @@ -53,7 +45,7 @@ 'sphinx.ext.viewcode', 'sphinx_autodoc_typehints', 'sphinx_design', - 'sphinx_tabs.tabs', + 'sphinx_immaterial', ] nitpicky = True modindex_common_prefix = ['betty.'] diff --git a/documentation/development.rst b/documentation/development.rst index 2dbb7683a..3a3f37115 100644 --- a/documentation/development.rst +++ b/documentation/development.rst @@ -13,7 +13,7 @@ Development This section covers how to develop Betty itself. -.. note:: +.. seealso:: Read :doc:`/about/contributing` if you would like to share your improvements to Betty with the wider community. Getting started diff --git a/documentation/development/extension.rst b/documentation/development/extension.rst index d001ca737..9a9520820 100644 --- a/documentation/development/extension.rst +++ b/documentation/development/extension.rst @@ -30,14 +30,17 @@ to enable and configure your extension for their project. Given an extension ``my_package.my_module.MyExtension``, add the following to your extension's Python package: -.. tabs:: - .. tab:: pyproject.toml +.. md-tab-set:: + + .. md-tab-item:: pyproject.toml + .. code-block:: toml [project.entry-points.'betty.extensions'] 'my_package.my_module.MyExtension' = 'my_package.my_module.MyExtension' - .. tab:: setup.py + .. md-tab-item:: setup.py + .. code-block:: python SETUP = { @@ -69,7 +72,7 @@ are located. This may be anywhere in your Python package. Dependencies ------------ -.. note:: +.. important:: Any dependencies on other Python packages must be declared by your extension's Python package. Extensions have fine-grained control over which other extensions they require, and the order in diff --git a/documentation/usage/ancestry.rst b/documentation/usage/ancestry.rst index e10973760..2ee7c35c9 100644 --- a/documentation/usage/ancestry.rst +++ b/documentation/usage/ancestry.rst @@ -25,8 +25,10 @@ analyzed, expanded, and ultimately generated into a site. In code, you will be using :py:class:`betty.model.ancestry.Ancestry`, through which you can access any entity of any type. -.. tabs:: - .. tab:: Python +.. md-tab-set:: + + .. md-tab-item:: Python + .. code-block:: python from betty.model.ancestry import Ancestry, Person @@ -36,7 +38,8 @@ access any entity of any type. ancestry.add(person) assert person is ancestry[Person]['a1b2'] - .. tab:: Jinja2 + .. md-tab-item:: Jinja2 + .. code-block:: jinja {% set people = ancestry['Person'] %} diff --git a/documentation/usage/extension/cotton_candy.rst b/documentation/usage/extension/cotton_candy.rst index ef9d3d966..3ca4909e6 100644 --- a/documentation/usage/extension/cotton_candy.rst +++ b/documentation/usage/extension/cotton_candy.rst @@ -4,14 +4,17 @@ 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: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml extensions: betty.extension.CottonCandy: {} - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { @@ -24,8 +27,10 @@ Configuration ------------- This extension is configurable through Betty Desktop or in the configuration file: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml extensions: @@ -41,7 +46,8 @@ This extension is configurable through Betty Desktop or in the configuration fil - entity_type: Place entity_id: Amsterdam - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { diff --git a/documentation/usage/extension/deriver.rst b/documentation/usage/extension/deriver.rst index bdaa68d99..dd5036a3c 100644 --- a/documentation/usage/extension/deriver.rst +++ b/documentation/usage/extension/deriver.rst @@ -11,14 +11,17 @@ 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: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml extensions: betty.extension.Deriver: {} - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { diff --git a/documentation/usage/extension/gramps.rst b/documentation/usage/extension/gramps.rst index d64c84f31..09cc0766d 100644 --- a/documentation/usage/extension/gramps.rst +++ b/documentation/usage/extension/gramps.rst @@ -4,14 +4,17 @@ The :py:class:`betty.extension.Gramps` extension loads entities from `Gramps ` as follows: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml extensions: betty.extension.Gramps: {} - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { @@ -24,8 +27,10 @@ Configuration ------------- This extension is configurable through Betty Desktop or in the configuration file: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml extensions: @@ -34,7 +39,8 @@ This extension is configurable through Betty Desktop or in the configuration fil family_trees: - file: ./gramps.gpkg - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { diff --git a/documentation/usage/extension/http_api_doc.rst b/documentation/usage/extension/http_api_doc.rst index 602c90004..829c1446e 100644 --- a/documentation/usage/extension/http_api_doc.rst +++ b/documentation/usage/extension/http_api_doc.rst @@ -5,14 +5,17 @@ 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: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml extensions: betty.extension.HttpApiDoc: {} - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { diff --git a/documentation/usage/extension/maps.rst b/documentation/usage/extension/maps.rst index bb75639e4..c49025731 100644 --- a/documentation/usage/extension/maps.rst +++ b/documentation/usage/extension/maps.rst @@ -5,14 +5,17 @@ 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: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml extensions: betty.extension.Maps: {} - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { diff --git a/documentation/usage/extension/nginx.rst b/documentation/usage/extension/nginx.rst index 1dbf1b32b..4cd0fa7e8 100644 --- a/documentation/usage/extension/nginx.rst +++ b/documentation/usage/extension/nginx.rst @@ -5,14 +5,17 @@ directory. Enable this extension through Betty Desktop, or in your project's :doc:`configuration file ` as follows: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml extensions: betty.extension.Nginx: {} - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { @@ -25,8 +28,8 @@ Configuration ------------- This extension is configurable through Betty Desktop or in the configuration file: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + .. md-tab-item:: YAML .. code-block:: yaml extensions: @@ -35,7 +38,7 @@ This extension is configurable through Betty Desktop or in the configuration fil www_directory_path: /var/www/betty https: true - .. tab:: JSON + .. md-tab-item:: JSON .. code-block:: json { diff --git a/documentation/usage/extension/privatizer.rst b/documentation/usage/extension/privatizer.rst index 9a9296ec7..263fd579d 100644 --- a/documentation/usage/extension/privatizer.rst +++ b/documentation/usage/extension/privatizer.rst @@ -45,14 +45,17 @@ Source Enable this extension through Betty Desktop, or in your project's :doc:`configuration file ` as follows: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml extensions: betty.extension.Privatizer: {} - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { diff --git a/documentation/usage/extension/trees.rst b/documentation/usage/extension/trees.rst index bcac4bc0d..0b1e871c2 100644 --- a/documentation/usage/extension/trees.rst +++ b/documentation/usage/extension/trees.rst @@ -4,14 +4,17 @@ 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: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml extensions: betty.extension.Trees: {} - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { diff --git a/documentation/usage/extension/wikipedia.rst b/documentation/usage/extension/wikipedia.rst index 1364b2908..f875fb2ba 100644 --- a/documentation/usage/extension/wikipedia.rst +++ b/documentation/usage/extension/wikipedia.rst @@ -6,14 +6,17 @@ render them on the entity's page. Enable this extension through Betty Desktop, or in your project's :doc:`configuration file ` as follows: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml extensions: betty.extension.Wikipedia: {} - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { diff --git a/documentation/usage/project.rst b/documentation/usage/project.rst index 0943b5505..173c1817a 100644 --- a/documentation/usage/project.rst +++ b/documentation/usage/project.rst @@ -16,7 +16,7 @@ You can create and tailor projects through the :doc:`Betty Desktop application` using :doc:`configuration files `. -.. note:: +.. important:: Betty will consider the directory your project configuration file is located in to be your project directory, and assumes that the directory will not be used for anything else besides your Betty project. diff --git a/documentation/usage/project/configuration.rst b/documentation/usage/project/configuration.rst index 5d4aba4d1..4ef6a9e7e 100644 --- a/documentation/usage/project/configuration.rst +++ b/documentation/usage/project/configuration.rst @@ -5,8 +5,10 @@ Project configuration files are written in YAML (``betty.yaml`` or ``betty.yml`` and are placed in the root of the project directory. Both YAML and JSON files follow the exact same structure. Example configuration: -.. tabs:: - .. tab:: YAML +.. md-tab-set:: + + .. md-tab-item:: YAML + .. code-block:: yaml base_url: https://ancestry.example.com @@ -27,7 +29,8 @@ structure. Example configuration: generate_html_list: false extensions: {} - .. tab:: JSON + .. md-tab-item:: JSON + .. code-block:: json { diff --git a/pyproject.toml b/pyproject.toml index cbcf94067..b9e2c054f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,8 +35,7 @@ dependencies = [ 'pyyaml ~= 6.0, >= 6.0.0', 'sphinx ~= 7.2.6', 'sphinx-design ~= 0.5.0', - 'sphinx-tabs ~= 3.4.4', - 'sphinx_rtd_theme ~= 2.0.0', + 'sphinx-immaterial ~= 0.11.10', 'sphinx-autodoc-typehints ~= 1.25.2', ] classifiers = [