Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add guidelines to Contributing Documentation #66

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add guidelines to Contributing Documentation #66

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bfa3e8e
Draft contributing docs guidelines
lochhh Oct 29, 2024
d05e601
Document update API reference
lochhh Oct 31, 2024
1b46b4c
Simplify `readme.md`
lochhh Oct 31, 2024
eb1b39a
Add clone repo as prereq in building docs locally
lochhh Nov 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 18 additions & 122 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,116 +1,22 @@
# aeon_docs

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

The docs are built via [Sphinx](https://www.sphinx-doc.org/en/master/), and hosted via GitHub Pages at [sainsburywellcomecentre.github.io/aeon_docs/](https://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:
```bash
conda create -n aeon_docs python dotnet -c conda-forge
conda activate aeon_docs
```

Make the `docfx` tool available in the environment:
```bash
dotnet tool restore
```

From the root of the repository, install the requirements for building the documentation:
```bash
pip install -r requirements.txt
```

Then, populate submodules:
```bash
git submodule init
git submodule update
```

(Optional) Update submodules and point to the latest commits:
```bash
git submodule sync
git submodule update --remote
```

Finally, build the documentation:
```bash
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:
```bash
make clean && make html
```

To check that external URLs are correctly resolved, run:
```bash
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.:
```python
# 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.:
```python
# 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.:
```python
# 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:
```bash
git fetch --tags
```

Identify the latest tag:
```bash
git describe --tags
```

Create a new tag:
```bash
git tag <tag_name>
```

Push the tag to the main branch:
```bash
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.
This repo contains the source for the [Aeon online documentation](https://sainsburywellcomecentre.github.io/aeon_docs/).

> [!CAUTION]
> The documentation is currently under active development and may be incomplete.
> Please report any issues or suggestions for improvement by [opening an issue](https://github.com/SainsburyWellcomeCentre/aeon_docs/issues).

To contribute to the documentation, please see the [Contributor Guide](https://sainsburywellcomecentre.github.io/aeon_docs/contributor/index.html).

## Aeon organisation overview

Aeon is a collaborative effort to perform behavioural neuroscience experiments where the behaviour 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](#project-maintainers).

## Credentials

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

- Microsoft Teams: contact [Jai Bhagat](mailto:[email protected]), [Gonçalo Lopes](mailto:[email protected]), or [Dario Campagner](mailto:[email protected])
- SWC Github organization: contact [SWC Helpdesk](mailto:[email protected])
Expand All @@ -122,19 +28,12 @@ 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](mailto:[email protected],[email protected],[email protected],[email protected],[email protected]?subject=Request%20for%20Aeon%20credentials) requesting this access.

## Repositories

> [!IMPORTANT]
> You must be an SWC Github `aeon` project member to view some of these repositories.

### [aeon_mecha](https://github.com/SainsburyWellcomeCentre/aeon_mecha)

![aeon_mecha_env_build_and_tests](https://github.com/SainsburyWellcomeCentre/aeon_mecha/actions/workflows/build_env_run_tests.yml/badge.svg?branch=main)
[![aeon_mecha_tests_code_coverage](https://codecov.io/gh/SainsburyWellcomeCentre/aeon_mecha/branch/main/graph/badge.svg?token=973EC1CG03)](https://codecov.io/gh/SainsburyWellcomeCentre/aeon_mecha)

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](https://www.cf-hw.org/harp). Code in the 'aeon_acquisition' and 'aeon_mecha' repos makes use of the [Harp protocol](https://harp-tech.org/articles/about.html) during data acquisition, raw data file writing, and raw data file reading. See also the documentation on [Harp device operation and common registers](https://harp-tech.org/protocol/Device.html), the [Harp binary protocol](https://harp-tech.org/protocol/BinaryProtocol-8bit.html), and [Harp clock synchronization](https://harp-tech.org/protocol/SynchronizationClock.html).
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.

### [aeon_experiments](https://github.com/SainsburyWellcomeCentre/aeon_experiments)

Expand All @@ -154,18 +53,15 @@ Contains low-level source code for pellet delivery via feeders used in Aeon expe

### [aeon_docs](https://github.com/SainsburyWellcomeCentre/aeon_docs)

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


## Project Maintainers

Jai Bhagat ([email protected])

Gonçalo Lopes ([email protected])

Dario Campagner ([email protected])

Chang Huan Lo ([email protected])
- Jai Bhagat ([email protected])
- Gonçalo Lopes ([email protected])
- Dario Campagner ([email protected])
- Chang Huan Lo ([email protected])

## Citation Policy

Expand Down
4 changes: 4 additions & 0 deletions src/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,13 +163,17 @@ def get_current_release_tag():
"https": None,
"ftp": None,
"mailto": None,
"aeon-docs": "https://sainsburywellcomecentre.github.io/aeon_docs/{{path}}",
"aeon-docs-github": "https://github.com/SainsburyWellcomeCentre/aeon_docs/{{path}}",
"aeon-mecha-github": "https://github.com/SainsburyWellcomeCentre/aeon_mecha/{{path}}",
"aeon-acquisition-github": "https://github.com/SainsburyWellcomeCentre/aeon_acquisition/{{path}}",
"aeon-experiments-github": "https://github.com/SainsburyWellcomeCentre/aeon_experiments/{{path}}",
"aeon-lineardrive-github": "https://github.com/SainsburyWellcomeCentre/aeon_lineardrive/{{path}}",
"aeon-feeder-github": "https://github.com/SainsburyWellcomeCentre/aeon_feeder/{{path}}",
"myst-parser": "https://myst-parser.readthedocs.io/en/latest/{{path}}#{{fragment}}",
"semver": "https://semver.org/",
"harp-tech": "https://harp-tech.org/{{path}}#{{fragment}}",
"python-pep": "https://peps.python.org/pep-{{path}}",
"sphinx-doc": "https://www.sphinx-doc.org/en/master/usage/{{path}}#{{fragment}}",
"niu-howto": "https://howto.neuroinformatics.dev/programming/SSH-SWC-cluster#{{fragment}}",
}
Loading
Loading