Apply new theme (#10)

* Switch to PyData Sphinx theme * Use zenodo "all-versions" doi * Test current branch in docs build workflow * Fetch tags in docs build workflow * Manually fetch tags
SainsburyWellcomeCentre · Dec 7, 2023 · cb9ba9f · cb9ba9f
1 parent e029440
commit cb9ba9f
Show file tree

Hide file tree

Showing 7 changed files with 105 additions and 71 deletions.
diff --git a/.github/workflows/docs_build_and_deploy.yml b/.github/workflows/docs_build_and_deploy.yml
@@ -9,6 +9,7 @@ on:
   push:
     branches:
       - main
+      - new-theme # temporarily add branch to test new theme deployment
     tags:
       - '*'
   pull_request:
@@ -19,10 +20,12 @@ jobs:
     name: Build Sphinx Docs
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: false # Disable automatic checkout of all submodules
-
+      - name: Fetch tags
+        run: |
+          git fetch --prune --prune-tags --force --depth=1 --no-recurse-submodules
       - name: Checkout public submodules # Skip aeon_experiments
         run: |
           git submodule sync

diff --git a/readme.md b/readme.md
@@ -106,8 +106,6 @@ Dario Campagner ([email protected])
 
 If you use this software, please cite it as below:
 
-Sainsbury Wellcome Centre Foraging Behaviour Working Group. (2023). Aeon: An open-source platform to study the neural basis of ethological behaviours over naturalistic timescales,  https://doi.org/10.5281/zenodo.8413142
-
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8413142.svg)](https://zenodo.org/doi/10.5281/zenodo.8411157)
-
+Sainsbury Wellcome Centre Foraging Behaviour Working Group. (2023). Aeon: An open-source platform to study the neural basis of ethological behaviours over naturalistic timescales,  https://doi.org/10.5281/zenodo.8411157
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8411157.svg)](https://zenodo.org/doi/10.5281/zenodo.8411157)
diff --git a/requirements.txt b/requirements.txt
@@ -3,9 +3,9 @@ dotmap
 matplotlib
 opencv-python
 pandas 
-importlib_metadata # remove when PR#281 is merged
 
 myst-parser
 linkify-it-py
 sphinx-design
-sphinx-autodoc-typehints
+sphinx-autodoc-typehints
+pydata-sphinx-theme
diff --git a/src/conf.py b/src/conf.py
@@ -11,6 +11,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import subprocess
 import sys
 from datetime import date
 
@@ -29,10 +30,28 @@
 project = "aeon_docs"
 copyright = f"2022–{date.today().year}, Jai Bhagat, Goncalo Lopes, Chang Huan Lo"
 author = "Jai Bhagat, Goncalo Lopes, Chang Huan Lo"
+organisation = "Sainsbury Wellcome Centre"
+
+
+def get_current_release_tag():
+    try:
+        # Get the current release tag from git
+        return (
+            subprocess.check_output(["git", "describe", "--tags", "--abbrev=0"])
+            .strip()
+            .decode("utf-8")
+        )
+    except subprocess.CalledProcessError:
+        # If this fails, just return a default
+        return ""
+
 
 # The full version, including alpha/beta/rc tags
-release = "0.1.0"
+release = get_current_release_tag()
+# release = "0.1.0"
 
+# GitHub repo URL
+github_url = f"https://github.com/{organisation.replace(' ', '')}/{project}"
 
 # -- General configuration ---------------------------------------------------
 
@@ -78,12 +97,26 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "pydata_sphinx_theme"
 html_theme_options = {
-    "github_user": "SainsburyWellcomeCentre",
-    "github_repo": "aeon_docs",
-    "github_button": True,
-    "github_count": None,
+    "announcement": f"{project} is a WIP. Please report any issues on <a href='{github_url}/issues'>GitHub</a>.",
+    "logo": {
+        "text": f"{project} {release}"
+        # "image_light": "_static/logo-light.png",
+        # "image_dark": "_static/logo-dark.png",
+    },
+    "icon_links": [
+        {
+            # Label for this link
+            "name": "GitHub",
+            # URL where the link will redirect
+            "url": github_url,
+            # Icon class (if "type": "fontawesome"), or path to local image (if "type": "local")
+            "icon": "fa-brands fa-github",
+            # The type of image to be used (see below for details)
+            "type": "fontawesome",
+        }
+    ],
 }
 # 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,

diff --git a/src/dev_practices/dev_practices.md → src/dev_practices/index.md b/src/dev_practices/dev_practices.md → src/dev_practices/index.md
@@ -1,4 +1,4 @@
-# Development Practices
+# Community
 
 ## Software Development Life Cycle (SDLC)
 

diff --git a/src/index.md b/src/index.md
@@ -1,60 +1,10 @@
 # Project Aeon
 
-ProjectAeon is a collaborative effort to perform behavioral neuroscience experiments where the behavior and neural activity of freely moving animals engaging in a complex task are continuously recorded. This project is contributed to by researchers and support staff at UCL's SWC, Neurogears, and Datajoint.
+ProjectAeon is a collaborative effort to perform behavioral neuroscience experiments where the behavior and neural activity of freely moving animals engaging in a complex task are continuously recorded. This project spans [multiple repositories](target-repositories) and is contributed to by researchers and support staff at UCL's SWC, Neurogears, and Datajoint.
 
 If you are interested in joining this project, please contact the [project maintainers](target-project-maintainers).
 
 
-## Repositories
-
-:::{important}
-You must be an SWC Github 'aeon' project member to view some of these repositories.
-:::
-
-::::{grid} 1 2 2 2
-:gutter: 3 
-
-:::{grid-item-card} {fas}`database;sd-text-primary` aeon_mecha
-:link: https://github.com/SainsburyWellcomeCentre/aeon_mecha
-:link-type: url
-Project Aeon's main library for interfacing with acquired data
-:::
-
-:::{grid-item-card} {fas}`flask;sd-text-primary` aeon_experiments
-:link: https://github.com/SainsburyWellcomeCentre/aeon_experiments
-:link-type: url
-Aeon experiment workflows written in the Bonsai visual programming language
-:::
-
-:::{grid-item-card} {fas}`computer;sd-text-primary` aeon_acquisition
-:link: https://github.com/SainsburyWellcomeCentre/aeon_acquisition
-:link-type: url
-Source code for the 'aeon_acquisition' Bonsai package used in Aeon experiment workflows
-:::
-
-:::{grid-item-card} {fas}`chart-line;sd-text-primary` aeon_analysis
-:link: https://github.com/SainsburyWellcomeCentre/aeon_analysis
-:link-type: url
-Python modules for analysis of Aeon experiment data
-:::
-
-:::{grid-item-card} {fas}`gear;sd-text-primary` aeon_lineardrive
-:link: https://github.com/SainsburyWellcomeCentre/aeon_lineardrive
-:link-type: url
-Source code for actuating a linear drive motor used in Aeon experiments
-:::
-
-:::{grid-item-card} {fas}`cookie-bite;sd-text-primary` aeon_feeder
-:link: https://github.com/SainsburyWellcomeCentre/aeon_feeder
-:link-type: url
-Source code for pellet delivery via feeders used in Aeon experiments
-:::
-::::
-
-:::{note}
-All experiment data is acquired and/or triggered and/or synced by [Harp devices](https://www.cf-hw.org/harp). Code in the 'aeon_acquisition' and 'aeon_mecha' repos makes use of the [Harp protocol](https://github.com/harp-tech/protocol) during data acquisition, raw data file writing, and raw data file reading. In the 'harp-tech/protocol' Github repo, you can find documentation on [Harp device operation and common registers](https://github.com/harp-tech/protocol/blob/master/Device%201.0%201.4%2020200901.pdf), the [Harp binary protocol](https://github.com/harp-tech/protocol/blob/master/Binary%20Protocol%201.0%201.1%2020180223.pdf), and [Harp clock synchronization](https://github.com/harp-tech/protocol/blob/master/Synchronization%20Clock%201.0%201.0%2020200712.pdf).
-:::
-
 (target-project-maintainers)=
 ## Project Maintainers
 
@@ -69,17 +19,17 @@ Dario Campagner ([email protected])
 
 If you use this software, please cite it as below:
 
-Sainsbury Wellcome Centre Foraging Behaviour Working Group. (2023). Aeon: An open-source platform to study the neural basis of ethological behaviours over naturalistic timescales,  https://doi.org/10.5281/zenodo.8413142
+Sainsbury Wellcome Centre Foraging Behaviour Working Group. (2023). Aeon: An open-source platform to study the neural basis of ethological behaviours over naturalistic timescales,  https://doi.org/10.5281/zenodo.8411157
 
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8413142.svg)](https://zenodo.org/doi/10.5281/zenodo.8411157)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8411157.svg)](https://zenodo.org/doi/10.5281/zenodo.8411157)
 
 :::{toctree}
 :maxdepth: 2
 :hidden:
 
-Home <self>
+repositories/index
 design_considerations
 data_contract
-Developer API <api>
-dev_practices/dev_practices
+API Reference <api>
+dev_practices/index
 glossary
diff --git a/src/repositories/index.md b/src/repositories/index.md
@@ -0,0 +1,50 @@
+(target-repositories)=
+# Repositories
+
+:::{important}
+You must be an SWC Github 'aeon' project member to view some of these repositories.
+:::
+
+::::{grid} 1 2 2 2
+:gutter: 3 
+
+:::{grid-item-card} {fas}`database;sd-text-primary` aeon_mecha
+:link: https://github.com/SainsburyWellcomeCentre/aeon_mecha
+:link-type: url
+Project Aeon's main library for interfacing with acquired data
+:::
+
+:::{grid-item-card} {fas}`flask;sd-text-primary` aeon_experiments
+:link: https://github.com/SainsburyWellcomeCentre/aeon_experiments
+:link-type: url
+Aeon experiment workflows written in the Bonsai visual programming language
+:::
+
+:::{grid-item-card} {fas}`computer;sd-text-primary` aeon_acquisition
+:link: https://github.com/SainsburyWellcomeCentre/aeon_acquisition
+:link-type: url
+Source code for the 'aeon_acquisition' Bonsai package used in Aeon experiment workflows
+:::
+
+:::{grid-item-card} {fas}`chart-line;sd-text-primary` aeon_analysis
+:link: https://github.com/SainsburyWellcomeCentre/aeon_analysis
+:link-type: url
+Python modules for analysis of Aeon experiment data
+:::
+
+:::{grid-item-card} {fas}`gear;sd-text-primary` aeon_lineardrive
+:link: https://github.com/SainsburyWellcomeCentre/aeon_lineardrive
+:link-type: url
+Source code for actuating a linear drive motor used in Aeon experiments
+:::
+
+:::{grid-item-card} {fas}`cookie-bite;sd-text-primary` aeon_feeder
+:link: https://github.com/SainsburyWellcomeCentre/aeon_feeder
+:link-type: url
+Source code for pellet delivery via feeders used in Aeon experiments
+:::
+::::
+
+:::{note}
+All experiment data is acquired and/or triggered and/or synced by [Harp devices](https://www.cf-hw.org/harp). Code in the 'aeon_acquisition' and 'aeon_mecha' repos makes use of the [Harp protocol](https://github.com/harp-tech/protocol) during data acquisition, raw data file writing, and raw data file reading. In the 'harp-tech/protocol' Github repo, you can find documentation on [Harp device operation and common registers](https://github.com/harp-tech/protocol/blob/master/Device%201.0%201.4%2020200901.pdf), the [Harp binary protocol](https://github.com/harp-tech/protocol/blob/master/Binary%20Protocol%201.0%201.1%2020180223.pdf), and [Harp clock synchronization](https://github.com/harp-tech/protocol/blob/master/Synchronization%20Clock%201.0%201.0%2020200712.pdf).
+:::