From 4649173903997440b7546eb495732602d5e0a492 Mon Sep 17 00:00:00 2001
From: Matthew Hambley <MatthewHambley@users.noreply.github.com>
Date: Wed, 17 Apr 2024 13:45:21 +0100
Subject: [PATCH] Migrated to PyData Sphinx theme (#299)

* Migrated to PyData Sphinx theme and fixed API generation.

* Downgrade theme version to one which is available.

* Bump depricated actions in workflow.

* Prefer a more modern flake8.

* Downgrade flake8 to pre v7.0.0.

* Another go at guessing the correct flake8 version.
---
 .github/workflows/build.yml                 |  4 +-
 docs/source/_templates/crown-copyright.html | 11 +++++
 docs/source/api.rst                         | 10 +++++
 docs/source/conf.py                         | 50 +++++++++++----------
 docs/source/index.rst                       |  2 +-
 pyproject.toml                              |  7 ++-
 6 files changed, 55 insertions(+), 29 deletions(-)
 create mode 100644 docs/source/_templates/crown-copyright.html
 create mode 100644 docs/source/api.rst

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index ded9d856..936c7bd9 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -12,9 +12,9 @@ jobs:
         python-version: ['3.7', '3.8', '3.9', '3.10']
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
     - name: Setup Compiler
diff --git a/docs/source/_templates/crown-copyright.html b/docs/source/_templates/crown-copyright.html
new file mode 100644
index 00000000..44657219
--- /dev/null
+++ b/docs/source/_templates/crown-copyright.html
@@ -0,0 +1,11 @@
+{# Crown copyright is displayed differently to normal. #}
+{# Configured from conf.py as per usual. #}
+{% if show_copyright and copyright %}
+<p class="copyright">
+    {% if hasdoc('copyright') %}
+    {% trans path=pathto('copyright'), copyright=copyright|e %}© <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
+    {% else %}
+    {% trans copyright=copyright|e %}© Crown Copyright {{ copyright }}.{% endtrans %}
+    {% endif %}
+</p>
+{% endif %}
diff --git a/docs/source/api.rst b/docs/source/api.rst
new file mode 100644
index 00000000..6a5a1bbd
--- /dev/null
+++ b/docs/source/api.rst
@@ -0,0 +1,10 @@
+API Documentation
+=================
+
+This API documentation is generated from comments within the source code.
+
+.. autosummary::
+   :toctree: api
+   :recursive:
+   
+   fab
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 68762f24..d036262f 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -17,8 +17,8 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'fab'
-copyright = '2023'
+project = 'Fab'
+copyright = '2024 Met Office. All rights reserved.'
 author = 'Fab Team'
 
 # The full version, including alpha/beta/rc tags
@@ -52,24 +52,35 @@
 exclude_patterns = []
 
 
-# -- Options for HTML output -------------------------------------------------
+# -- Autodoc -----------------------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
+autodoc_default_options = {
+    'members': True,
+    'show-inheritane': True
+}
 
-# ugly
-# html_theme = "classic"
+autoclass_content = 'both'
 
-# poor contrast between title, h1 & h2
-# html_theme = "sphinxdoc"
-# html_theme = "sphinx_rtd_theme"
-# html_theme = 'python_docs_theme'
 
-# good contrast between title, h1 & h2
-# html_theme = 'alabaster'
-html_theme = 'sphinx_material'
+# -- Options for HTML output -------------------------------------------------
 
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'pydata_sphinx_theme'
+
+html_theme_options = {
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/metomi/fab",
+            "icon": "fa-brands fa-github"
+        }
+    ],
+    "footer_start": ["crown-copyright"],
+    "footer_center": ["sphinx-version"],
+    "footer_end": ["theme-version"],
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -93,12 +104,3 @@
 
 # include default values in argument descriptions
 typehints_defaults = 'braces-after'
-
-# needed when using material theme
-html_sidebars = {
-    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
-}
-# needed when not using material theme
-# html_sidebars = {
-#     "**": ["globaltoc.html", "searchbox.html"]
-# }
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 0b5458c7..fc03936e 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -81,7 +81,7 @@ See also
    writing_config
    advanced_config
    features
-   Api Reference <apidoc/modules>
+   Api Reference <api>
    development
    glossary
    genindex
diff --git a/pyproject.toml b/pyproject.toml
index 9e242d43..76424ead 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -22,8 +22,11 @@ classifiers = [
 c-language = ['python-clang']
 plots = ['matplotlib']
 tests = ['pytest', 'pytest-cov', 'pytest-mock']
-checks = ['flake8', 'mypy']
-docs = ['sphinx', 'sphinx-material', 'sphinx-autodoc-typehints', 'sphinx-copybutton']
+checks = ['flake8>=5.0.4', 'mypy']
+docs = ['sphinx',
+        'pydata-sphinx-theme>=0.13.3',
+        'sphinx-autodoc-typehints',
+        'sphinx-copybutton']
 dev = ['sci-fab[plots, tests, checks, docs]']
 
 [project.scripts]