Merge pull request #46 from lochhh/feedback

Incorporate feedback

.gitmodules

@@ -1,7 +1,7 @@
 [submodule "aeon_mecha"]
 	path = aeon_mecha
 	url = https://github.com/SainsburyWellcomeCentre/aeon_mecha
-	branch = main
+	branch = data-preview
 [submodule "aeon_analysis"]
 	path = aeon_analysis
 	url = https://github.com/SainsburyWellcomeCentre/aeon_analysis

copy_examples_to_src.py

@@ -29,6 +29,7 @@ def copy_ipynb_files(src_dirs: str | list[str], dst_dir: str) -> None:
 
 
 if __name__ == "__main__":
-    src_dir = "./aeon_mecha/aeon/dj_pipeline/docs/notebooks/"
-    dst_dir = "./src/user/how_to/"
-    copy_ipynb_files(src_dir, dst_dir)
+    src_dir = os.path.join("aeon_mecha", "docs", "examples")
+    dst_dir = os.path.join("src", "user", "how_to")
+    print(src_dir, dst_dir)
+    copy_ipynb_files(src_dir, dst_dir)

src/_static/css/custom.css

@@ -35,7 +35,5 @@ html[data-theme=light] {
 }
 
 .sd-card-img-bottom {
-  width: 100%;
-  height: 15vw;
   object-fit: contain;
 }

src/getting_started/index.md

@@ -1,9 +1,6 @@
 (target-getting-started)=
 # Getting Started
 
-<!-- Discover how Aeon allows us to record and quantify different natural behaviours, 
-such as foraging, nesting, escape and social interaction, and their neural basis, 
-continuously over multiple weeks. -->
 Aeon is an open-source platform designed to study the neural basis of natural behaviours over naturalistic timescales, from weeks to months. 
 It features a modular, scalable, and programmable arena where animals live. 
 Equipped with various [interactive and non-interactive modules](target-hardware) like feeders, nesting areas, microphones, RFID readers, and high-speed cameras, this setup mimics complex environments, allowing 
@@ -37,10 +34,66 @@ Week-long recording and analysis of Neuropixels data.
 :::
 ::::
 
+(target-repositories)=
+## Repositories
+The Aeon infrastructure is complex and multi-dimensional, spanning hardware, acquisition software, standard data formats, and a low-level API for data analysis. 
+As each of these different components is built using different languages, spanning CAD programs, C# and Python, we organise Aeon into the following 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
+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` repositories makes use of 
+the [Harp protocol](harp-tech:articles/about) during data acquisition, 
+raw data file writing, and raw data file reading. 
+See also the documentation on 
+[Harp device operation and common registers](harp-tech:protocol/Device), 
+the [Harp binary protocol](harp-tech:protocol/BinaryProtocol-8bit), and 
+[Harp clock synchronization](harp-tech:protocol/SynchronizationClock).
+:::
+
 :::{toctree}
 :maxdepth: 1
 :hidden:
 
-repositories
 installation
 :::

src/reference/api.md

@@ -1,6 +1,30 @@
 (target-api-reference)=
 # API Reference
 
+::::{grid} 2
+:gutter: 3 
+
+:::{grid-item-card} Data API Reference
+:link: target-mecha-reference
+:link-type: ref
+:img-bottom: ../_static/images/api-python-logo.png
+:class-img-bottom: sd-px-2
+:class-card: sd-height-25
+
+This reference guide contains a detailed description of the `aeon_mecha` low-level API.
+:::
+
+:::{grid-item-card} Acquisition API Reference
+:link: target-acquisition-reference
+:link-type: ref
+:img-bottom: ../_static/images/api-bonsai-logo.png
+:class-img-bottom: sd-px-2
+:class-card: sd-height-25
+
+This reference guide contains a detailed description of the `aeon_acquisition` API.
+:::
+::::
+
 :::{toctree}
 :maxdepth: 2
 :hidden:

src/reference/glossary.md

@@ -1,11 +1,12 @@
+(target-glossary)=
 # Glossary
 
 This glossary provides definitions for terms used throughout the project documentation.
 
 :::{glossary}
 
 Aeon
-    The source of all being. [^1]
+    A very long, indefinite period of time. [^1]
 
 Session
     For experiment 0.1, the event over the time period when an animal is placed in the nesting cage until the time the animal is removed from the nesting cage.
@@ -33,4 +34,4 @@ Task Protocol
 
 :::
 
-[^1]: https://en.wikipedia.org/wiki/Aeon_(Gnosticism)
+[^1]: https://en.wikipedia.org/wiki/Aeon

src/reference/hardware.md

@@ -4,11 +4,35 @@ This section is still under construction. Some information may be incomplete or
 
 (target-hardware)=
 # Hardware Overview
+## Main modules
+| Module | Files |
+| --- | --- |
+| **Arena** <br>![arena](../_static/images/hardware-overview-arena.png){height=15em align=center} | <ul><li>[Assembly guide](../_static/resources/Arena%20guideline%20Final%201.pdf)</li><li>[Bill of materials](../_static/resources/Arena%20BOM.xlsx)</li></ul> |
+| **Feeder** <br>![feeder](../_static/images/hardware-overview-feeder.png){height=12em align=center} | <ul><li>[Assembly guide](../_static/resources/Feeder%20Guideline%20Final%201.pdf)</li><li>[Bill of materials](../_static/resources/Feeder%20BOM.xlsx)</li></ul> |
+| **Nest** <br>![nest](../_static/images/hardware-overview-nest.png){height=15em align=center} | <ul><li>[Assembly guide](../_static/resources/Nest%20Guideline%20Final%201.pdf)</li></ul> |
+| **Closed-loop translation-commutation system** <br>![linear-rail](../_static/images/hardware-overview-linear-rail.png){height=15em align=center} | <ul><li>[Assembly guide](../_static/resources/Linear%20commutator%20Guideline%20Final%201.pdf)</li></ul> |
 
-This section describes the hardware components available in Aeon. 
+## Harp devices
+| Harp Device                       | Associated Component            | Description                                                   | Quantity | 
+|-----------------------------------|---------------------------------|---------------------------------------------------------------|----------|
+| [**Harp Output Expander**](harp-tech:api/Harp.OutputExpander.html)                  |  Foraging Patches (Feeders)      | Expander module to connect feeder to harp system. 1 per patch | 4        |
+| [**Harp CameraController Gen2**](harp-tech:api/Harp.CameraControllerGen2.html)    | Cameras                         | Controller to trigger all cameras in the arena                | 1        |
+| [**Harp Timestamp Generator Gen3**](harp-tech:api/Harp.TimestampGeneratorGen3.html) | Arena (Synchronizes all devices)| Synchronizes all harp devices in the arena                    | 1        |
+| [**Micropython Harp device**](https://github.com/SainsburyWellcomeCentre/microharp)       | Ephys linear rail drive         | Linear rail position controller and position sensor reciever  | 1        | 
+| [**Harp SoundCard**](harp-tech:api/Harp.SoundCard.html)                  | SP speaker                      | Control and monitoring of audio speaker                     | 1        | 
+
+## Wiring diagrams
+- [Wiring diagram](../_static/resources/Example%20wiring%20diagram.pdf)
+
+<!--
+:::{toctree}
+:maxdepth: 1
+:hidden:
+hardware/feeder
 
 ::::{grid} 1 3 3 3 
 :::{grid-item-card} Feeder
+:img-top: ../_static/images/hardware-overview-feeder.png
 :link: target-feeder
 :link-type: ref
 :img-bottom: ../_static/images/hardware-overview-feeder.png
@@ -22,8 +46,4 @@ This section describes the hardware components available in Aeon.
 :img-bottom: ../_static/images/hardware-overview-nest.png
 :::
 ::::
-
-:::{toctree}
-:maxdepth: 1
-:hidden:
-hardware/feeder
+-->

src/reference/index.md

@@ -1,7 +1,35 @@
 (target-reference)=
 # Reference
 
-This reference manual details all software and hardware components, and a glossary of terms used in Project Aeon. It describes what these components are and how they function. For a comprehensive guide on how to use Project Aeon, please refer to the [complete documentation](target-home).
+This reference manual details all software and hardware components, and a glossary of terms used in Aeon. It describes what these components are and how they function. For a comprehensive guide on how to use Aeon, please refer to the [complete documentation](target-home).
+
+::::{grid} 1 2 2 2
+:gutter: 3 
+
+:::{grid-item-card} {fas}`microchip;sd-text-primary` Hardware Overview
+:link: target-hardware
+:link-type: ref
+<!-- :img-bottom: ../_static/images/getting-started-ma.png -->
+:::
+
+:::{grid-item-card} {fas}`code;sd-text-primary` API Reference
+:link: target-api-reference
+:link-type: ref
+<!-- :img-bottom: ../_static/images/getting-started-npx.png -->
+:::
+
+:::{grid-item-card} {fas}`folder-tree;sd-text-primary` Data Contract
+:link: target-data-schema
+:link-type: ref
+<!-- :img-bottom: ../_static/images/getting-started-npx.png -->
+:::
+
+:::{grid-item-card} {fas}`book-bookmark;sd-text-primary` Glossary
+:link: target-glossary
+:link-type: ref
+<!-- :img-bottom: ../_static/images/getting-started-npx.png -->
+:::
+::::
 
 :::{toctree}
 :maxdepth: 2