Skip to content

Latest commit

 

History

History
180 lines (127 loc) · 7.43 KB

readme.md

File metadata and controls

180 lines (127 loc) · 7.43 KB
Raw

aeon_docs

This repo contains the source for the currently WIP version of Project Aeon's online docs.

The docs are built via Sphinx, and hosted via GitHub Pages at sainsburywellcomecentre.github.io/aeon_docs/. src/ is the Sphinx source directory, and the site is built and deployed from the gh-pages branch. This is handled by a GitHub actions workflow (.github/workflows/docs_build_and_deploy.yml). The build job is triggered on each PR, ensuring that the documentation build is not broken by new changes. The deployment job is only triggered whenever a tag is pushed to the main branch.

Building the documentation locally

Create a conda environment with the required dependencies and activate it:

conda create -n aeon_docs python dotnet -c conda-forge
conda activate aeon_docs

Make the docfx tool available in the environment:

dotnet tool restore

From the root of the repository, install the requirements for building the documentation:

pip install -r requirements.txt

Then, populate submodules:

git submodule init
git submodule update

(Optional) Update submodules and point to the latest commits:

git submodule sync
git submodule update --remote

Finally, build the documentation:

make html

You can view the local build by opening docs/html/index.html in a browser.

To apply new changes to the documentation, remove all automatically generated files and folders, and rebuild:

make clean && make html

To check that external URLs are correctly resolved, run:

make linkcheck

If the linkcheck step incorrectly marks URLs with valid anchors as broken, you can skip checking the anchors in specific URLs by adding them to linkcheck_anchors_ignore_for_url in src/conf.py, e.g.:

# linkcheck will skip verifying that anchors exist when checking
# these URLs
linkcheck_anchors_ignore_for_url = [
    "https://example.com",
]

To skip linkcheck for specific URLs, add them to linkcheck_ignore in src/conf.py, e.g.:

# linkcheck will skip checking these URLs entirely
linkcheck_ignore = [
    "https://github.com/org/private_repository",
]

To suppress warnings for expected redirects, add them to linkcheck_allowed_redirects in src/conf.py, e.g.:

# linkcheck will treat redirections from these source URI:canonical URI
# mappings as "working".
linkcheck_allowed_redirects = {
    r"https://zenodo\.org/doi/.*": r"https://zenodo\.org/records/.*",
}

Deploying the documentation

As mentioned above, the deployment job is triggered whenever a tag is pushed to the main branch. To deploy the documentation, follow these steps:

Fetch all tags:

git fetch --tags

Identify the latest tag:

git describe --tags

Create a new tag:

git tag <tag_name>

Push the tag to the main branch:

git push origin <tag_name>

Project Aeon Organization Overview

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.

If you are interested in joining this project, please contact the project maintainers.

Credentials

Below are the required sets of credentials for Project Aeon's members:

To be granted these credentials, please send a single email to all contact parties requesting this access.

Repositories

Important

You must be an SWC Github aeon project member to view some of these repositories.

aeon_mecha

aeon_mecha_env_build_and_tests aeon_mecha_tests_code_coverage

Project Aeon's main library for interfacing with acquired data. Contains Python modules for raw data file io, data querying, data processing, data qc, database ingestion, and building computational data pipelines. This is the main user repository.

Note

All experiment data is acquired and/or triggered and/or synced by Harp devices. Code in the 'aeon_acquisition' and 'aeon_mecha' repos makes use of the Harp protocol during data acquisition, raw data file writing, and raw data file reading. See also the documentation on Harp device operation and common registers, the Harp binary protocol, and Harp clock synchronization.

aeon_experiments

Contains experiment workflows written in the Bonsai visual programming language.

aeon_acquisition

Contains the source code for the 'aeon_acquisition' Bonsai package, which is heavily used in workflows in 'aeon_experiments'.

aeon_analysis

Contains Python modules for analysis of Aeon experiment data.

aeon_lineardrive

Contains source code for actuating a linear drive motor used in Aeon experiments (designed primarily for moving electrophysiology cabling during freely-moving experiments).

aeon_feeder

Contains low-level source code for pellet delivery via feeders used in Aeon experiments.

aeon_docs

Contains source code for the Aeon docs site, built via Sphinx. Built docs at: https://sainsburywellcomecentre.github.io/aeon_docs/

Project Maintainers

Jai Bhagat ([email protected])

Gonçalo Lopes ([email protected])

Dario Campagner ([email protected])

Chang Huan Lo ([email protected])

Citation Policy

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.8411157

DOI