Use the sphinx-immaterial for the documentation site. (#1258)

bartfeenstra · Feb 9, 2024 · 5e43fe4 · 5e43fe4
1 parent 40242cc
commit 5e43fe4
Show file tree

Hide file tree

Showing 18 changed files with 98 additions and 66 deletions.
diff --git 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 <https://twitter.com/Betty_Project>`_
-- :fab:`x-twitter` `X <https://twitter.com/Betty_Project>`_
-- :fab:`github` `Github <https://github.com/bartfeenstra/betty>`_
-- :fab:`python` `PyPI <https://pypi.org/project/betty>`_
+- :si-icon:`fontawesome/brands/twitter` `Twitter <https://twitter.com/Betty_Project>`_
+- :si-icon:`fontawesome/brands/github` `Github <https://github.com/bartfeenstra/betty>`_
+- :si-icon:`fontawesome/brands/python` `PyPI <https://pypi.org/project/betty>`_
 
 In this section
 ---------------

diff --git 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 <https://www.gnu.org/licenses/gpl-3.0.en.html>`_ 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 </usage/project/configuration>` 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
@@ -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 </usage/project/configuration>` 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
@@ -4,14 +4,17 @@ The :py:class:`betty.extension.Gramps` extension loads entities from `Gramps <ht
 
 Enable this extension through Betty Desktop, or in your project's :doc:`configuration file </usage/project/configuration>` 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
@@ -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 </usage/project/configuration>` 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
@@ -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 </usage/project/configuration>` 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
@@ -5,14 +5,17 @@ directory.
 
 Enable this extension through Betty Desktop, or in your project's :doc:`configuration file </usage/project/configuration>` 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
@@ -45,14 +45,17 @@ Source
 
 Enable this extension through Betty Desktop, or in your project's :doc:`configuration file </usage/project/configuration>` 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
@@ -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 </usage/project/configuration>` 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
@@ -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 </usage/project/configuration>` 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
@@ -16,7 +16,7 @@ You can create and tailor projects through the :doc:`Betty Desktop application</
 or through the :doc:`command line </usage/cli>` using :doc:`configuration files </usage/project/configuration>`.
 
 
-.. 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.