From bfa3e8e2641a73e2ab77fc6869ea878e13f93e6a Mon Sep 17 00:00:00 2001 From: lochhh Date: Tue, 29 Oct 2024 18:23:58 +0000 Subject: [PATCH 1/4] Draft contributing docs guidelines --- src/conf.py | 3 + src/contributor/index.md | 212 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 211 insertions(+), 4 deletions(-) diff --git a/src/conf.py b/src/conf.py index 40bef61c..0e4d4787 100644 --- a/src/conf.py +++ b/src/conf.py @@ -163,11 +163,14 @@ 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}}", diff --git a/src/contributor/index.md b/src/contributor/index.md index 31abd0bc..86065ccd 100644 --- a/src/contributor/index.md +++ b/src/contributor/index.md @@ -1,3 +1,4 @@ +(target-contributor-guide)= # Contributor Guide ## Software Development Life Cycle (SDLC) @@ -17,16 +18,15 @@ We version all the following, according to [SemVer](semver:) numbering: - aeon-db Database - aeon-db tables -## Issue Tracking +## Issue tracking We prioritize and track dev progress using Github Discussions and Github Issues in Github Projects. Issues and Discussions should ideally be created in the specific repository appropriate for the Issue/Discussion; all experiment and general Issues and Discussions should be created in 'aeon_experiments'. -## Continuous Integration (CI) +## Continuous integration (CI) We use Github Actions to run CI. We run unit tests on Github Virtual Machines on Windows, MacOS, and Ubuntu. We run integration tests on the SWC HPC. Workflows of the CI jobs we run can be found in each repo's respective `.github/workflows/` directory. -## Contributing - +## Contributing code Each repository roughly follows the [github flow](https://docs.github.com/en/get-started/using-github/github-flow) (which is adapted from the more general [gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)). @@ -42,6 +42,210 @@ All pull requests will be reviewed by the [project maintainers](target-project-m 3) When a branch is ready to be merged back into 'main', always make sure to first pull 'main' locally, then rebase the feature branch onto 'main' (cleaning up any merge conflicts as necessary), before merging the PR. The squash merge into 'prod' can be handled via CI. E.g., see [here](aeon-mecha-github:blob/main/.github/workflows/squash_merge_to_prod.yml) +## Contributing documentation +The documentation is built via [Sphinx](https://www.sphinx-doc.org/en/master/), +and hosted via GitHub Pages at [sainsburywellcomecentre.github.io/aeon_docs/](aeon-docs:). +`src/` is the Sphinx source directory, where you can find the Markdown (`.md`) and RestructuredText (`.rst`) files that make up the documentation. +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`), triggered by the following events: +- **Push to the main branch** +- **Tag push** +- **Pull request** +- **Manual dispatch** via the "Run workflow" button in the Actions tab. + +The workflow comprises two jobs: `build_sphinx_docs` and `deploy_sphinx_docs`. +The build job is triggered by all the listed events to ensure the documentation build remains intact with new changes. +The deployment job is only triggered on manual dispatch or [when a tag is pushed](#deploying-the-documentation). + +### Editing the documentation +To edit the documentation, clone the [`aeon_docs` repository](aeon-docs-github:), and work on a new branch, following the same guidelines as for [code changes](#contributing-code). Make sure that the header levels in the `.md` or `.rst` files are incremented consistently (H1 > H2 > H3, etc.) without skipping any levels. + +#### Adding a new page +If you are adding a new documentation source file (e.g. `new_file.md` or `new_file.rst`), +you will need to add it to the [`toctree` directive](myst-parser:syntax/organising_content.html#using-toctree-to-include-other-documents-as-children) +in the parent file (i.e. the page that will contain the link to the new page) +for it to be included in the documentation website. +Depending on the file format of the parent file (`.md`or `.rst`), the `toctree` directive syntax will differ. + +::::{tab-set} +:::{tab-item} Markdown +For example, to add `new_file.md` or `new_file.rst` under [Contributor Guide](aeon-docs:contributor), +you would add `new_file` to the `toctree` in `src/contributor/index.md` as follows: +```markdown +:::{toctree} +:maxdepth: 1 +:hidden: + +new_file +``` +This new page will then be included as a section under [Contributor Guide](aeon-docs:contributor). +::: + +:::{tab-item} RestructuredText +If the parent file is a `.rst` file, you would add `new_file` to the `toctree` in the parent file as follows: +```rst +.. toctree:: + :maxdepth: 1 + :hidden: + + new_file +``` +This new page will then be included as a section under the parent page. +::: +:::: + +#### Cross-referencing pages +##### Internal references +For ease of referencing, we use [explicit targets](myst-parser:syntax/cross-referencing#creating-explicit-targets) to refer to specific pages and sections within the documentation. +::::{tab-set} +:::{tab-item} Markdown +To create an explicit target in a `.md` file, use the `(target-name)=` syntax and add the target name before the page/section header, e.g.: +```markdown +(target-hardware)= +# Hardware Overview +``` +To reference the [](target-hardware) section, use the `[](target-name)` syntax: +```markdown +[](target-hardware) +``` +The link text will be displayed as the title of the referenced section. + +To display a custom link text (e.g. [custom text](target-hardware)), use the `[link text](target-name)` syntax: +```markdown +[custom text](target-hardware) +``` +::: + +:::{tab-item} RestructuredText +To create an explicit target in a `.rst` file, use the `.. _target-name:` syntax and add the target name before the page/section header, e.g.: +```rst +.. _target-hardware: + +Hardware Overview +================= +``` +To reference the [](target-hardware) section, use the `` :ref:`target-name` `` syntax, e.g.: +```rst +:ref:`target-hardware` +``` +The link text will be displayed as the title of the referenced section. + +To display a custom link text (e.g. [custom text](target-hardware)), use the `` :ref:`link text` `` syntax, e.g.: +```rst +:ref:custom text` +``` +::: +:::: + +##### External references +If you are adding references to an external URL (e.g. `https://github.com/SainsburyWellcomeCentre/aeon_docs/issues`) in a `.md` file, you will need to check if a matching URL scheme (e.g. `https://github.com/SainsburyWellcomeCentre/aeon_docs/`) is defined in `myst_url_schemes` in `src/conf.py`. If it is, the following `[](scheme:loc)` syntax will be converted to the [full URL](aeon-docs-github:issues/1) during the build process: +```markdown +[link text](aeon-docs-github:issues/1) +``` + +If it is not yet defined and you have multiple external URLs pointing to the same base URL, you will need to [add the URL scheme](myst-parser:syntax/cross-referencing#customising-external-url-resolution) to `myst_url_schemes` in `src/conf.py`. + +#### Updating the API reference +... + +### 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 +``` + +Push the tag to the main branch: +```bash +git push origin +``` + :::{toctree} :maxdepth: 1 :hidden: From d05e60139ad4bf366f23c5eb34ea6553500ab725 Mon Sep 17 00:00:00 2001 From: lochhh Date: Thu, 31 Oct 2024 14:58:19 +0000 Subject: [PATCH 2/4] Document update API reference --- src/conf.py | 1 + src/contributor/index.md | 49 ++++++++++++++++++++++++++++------------ 2 files changed, 35 insertions(+), 15 deletions(-) diff --git a/src/conf.py b/src/conf.py index 0e4d4787..765e6512 100644 --- a/src/conf.py +++ b/src/conf.py @@ -174,5 +174,6 @@ def get_current_release_tag(): "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}}", } diff --git a/src/contributor/index.md b/src/contributor/index.md index 86065ccd..6efc669c 100644 --- a/src/contributor/index.md +++ b/src/contributor/index.md @@ -58,19 +58,20 @@ The build job is triggered by all the listed events to ensure the documentation The deployment job is only triggered on manual dispatch or [when a tag is pushed](#deploying-the-documentation). ### Editing the documentation -To edit the documentation, clone the [`aeon_docs` repository](aeon-docs-github:), and work on a new branch, following the same guidelines as for [code changes](#contributing-code). Make sure that the header levels in the `.md` or `.rst` files are incremented consistently (H1 > H2 > H3, etc.) without skipping any levels. +To edit the documentation, clone the [`aeon_docs` repository](aeon-docs-github:), and work on a new branch, following the same guidelines as for [code changes](#contributing-code). +We recommend [building the documentation locally](#building-the-documentation-locally) to check that the changes are rendered correctly before pushing them to the repository. #### Adding a new page If you are adding a new documentation source file (e.g. `new_file.md` or `new_file.rst`), -you will need to add it to the [`toctree` directive](myst-parser:syntax/organising_content.html#using-toctree-to-include-other-documents-as-children) -in the parent file (i.e. the page that will contain the link to the new page) -for it to be included in the documentation website. +you will need to place the file in the appropriate directory within `src/`. +In each directory, you will find a parent file (typically an `index.md` or `index.rst` file) that serves as the main page for the subpages in that directory. +For the new file to be included in the documentation, you will need to add an entry for the new file in the [`toctree` directive](myst-parser:syntax/organising_content.html#using-toctree-to-include-other-documents-as-children) in the parent file. Depending on the file format of the parent file (`.md`or `.rst`), the `toctree` directive syntax will differ. ::::{tab-set} :::{tab-item} Markdown -For example, to add `new_file.md` or `new_file.rst` under [Contributor Guide](aeon-docs:contributor), -you would add `new_file` to the `toctree` in `src/contributor/index.md` as follows: +For example, to add `new_file.md` or `new_file.rst` as a subpage of the [Contributor Guide](aeon-docs:contributor), place the new file in `src/contributor/`. +As the parent file is `src/contributor/index.md`, add `new_file` to the `toctree` in the parent file as follows: ```markdown :::{toctree} :maxdepth: 1 @@ -78,11 +79,11 @@ you would add `new_file` to the `toctree` in `src/contributor/index.md` as follo new_file ``` -This new page will then be included as a section under [Contributor Guide](aeon-docs:contributor). +This new page will then be included as a subpage of [Contributor Guide](aeon-docs:contributor). ::: :::{tab-item} RestructuredText -If the parent file is a `.rst` file, you would add `new_file` to the `toctree` in the parent file as follows: +If the parent file is a `.rst` file, add `new_file` to the `toctree` in the parent file as follows: ```rst .. toctree:: :maxdepth: 1 @@ -90,13 +91,13 @@ If the parent file is a `.rst` file, you would add `new_file` to the `toctree` i new_file ``` -This new page will then be included as a section under the parent page. +This new page will then be included as a subpage of the parent page. ::: :::: #### Cross-referencing pages ##### Internal references -For ease of referencing, we use [explicit targets](myst-parser:syntax/cross-referencing#creating-explicit-targets) to refer to specific pages and sections within the documentation. +For ease of referencing, we use [explicit targets](myst-parser:syntax/cross-referencing.html#creating-explicit-targets) to refer to specific pages and sections within the documentation. ::::{tab-set} :::{tab-item} Markdown To create an explicit target in a `.md` file, use the `(target-name)=` syntax and add the target name before the page/section header, e.g.: @@ -143,10 +144,19 @@ If you are adding references to an external URL (e.g. `https://github.com/Sainsb [link text](aeon-docs-github:issues/1) ``` -If it is not yet defined and you have multiple external URLs pointing to the same base URL, you will need to [add the URL scheme](myst-parser:syntax/cross-referencing#customising-external-url-resolution) to `myst_url_schemes` in `src/conf.py`. +If it is not yet defined and you have multiple external URLs pointing to the same base URL, you will need to [add the URL scheme](myst-parser:syntax/cross-referencing.html#customising-external-url-resolution) to `myst_url_schemes` in `src/conf.py`. #### Updating the API reference -... +The [API reference](target-api-reference) is auto-generated as part of the documentation build process. + +##### `aeon_mecha` +For the `aeon_mecha` Python package, the `make_mecha_doctree.py` script generates the `src/reference/api/mecha.rst` file containing the list of modules to be included in the [API reference](target-mecha-reference). +The [sphinx-autodoc](sphinx-doc:extensions/autodoc.html) and [sphinx-autosummary](sphinx-doc:extensions/autosummary.html) extensions are then used to generate the API reference pages for each module listed in `mecha.rst`, based on the docstrings in the source code. +By default, all modules are documented. If you wish to exclude a module from the API reference, you can add it to the `ignore_modules` list in the `make_mecha_doctree.py` script. + +##### `aeon_acquisition` +For the `aeon_acquisition` Bonsai package, the `make_acquisition_doctree.py` script first calls [`docfx`](https://dotnet.github.io/docfx/index.html) to generate the API reference pages for each module as Markdown files in `src/reference/api/acquisition/`, and the table of contents (TOC) in the `src/reference/api/acquisition/toc.yml` file. +This TOC is then used to generate the `src/reference/api/acquisition.rst` file containing the list of modules to be included in the [API reference](target-acquisition-reference). ### Building the documentation locally Create a `conda` environment with the required dependencies and activate it: @@ -224,7 +234,16 @@ linkcheck_allowed_redirects = { ``` ### 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: +As mentioned above, the deployment job is triggered by the following events: +- **Tag push**: for releasing a new version of the documentation +- **Manual dispatch**: for testing purposes + +#### Manual dispatch +To deploy the documentation manually on GitHub, go to the Actions tab of the repository, +select the `Docs` workflow, and click "Run workflow". + +#### Tag push +To deploy the documentation with a new tag, follow these steps: Fetch all tags: ```bash @@ -236,12 +255,12 @@ Identify the latest tag: git describe --tags ``` -Create a new tag: +Create a new tag by incrementing the [version](#versioning) number: ```bash git tag ``` -Push the tag to the main branch: +Push the tag to the remote repository: ```bash git push origin ``` From 1b46b4c4d46ea229b191fcee061b7780e2a25f94 Mon Sep 17 00:00:00 2001 From: lochhh Date: Thu, 31 Oct 2024 15:52:51 +0000 Subject: [PATCH 3/4] Simplify `readme.md` --- readme.md | 140 +++++++----------------------------------------------- 1 file changed, 18 insertions(+), 122 deletions(-) diff --git a/readme.md b/readme.md index ef3951b7..3fc14367 100644 --- a/readme.md +++ b/readme.md @@ -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 -``` - -Push the tag to the main branch: -```bash -git push origin -``` - -## 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:jai.bhagat.21@ucl.ac.uk), [Gonçalo Lopes](mailto:g.lopes@neurogears.org), or [Dario Campagner](mailto:d.campagner@ucl.ac.uk) - SWC Github organization: contact [SWC Helpdesk](mailto:helpdesk@swc.ucl.ac.uk) @@ -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:jai.bhagat.21@ucl.ac.uk,g.lopes@neurogears.org,d.campagner@ucl.ac.uk,helpdesk@swc.ucl.ac.uk,thinh@vathes.com?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) @@ -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 (jai.bhagat.21@ucl.ac.uk) - -Gonçalo Lopes (g.lopes@neurogears.org) - -Dario Campagner (d.campagner@ucl.ac.uk) - -Chang Huan Lo (changhuan.lo@ucl.ac.uk) +- Jai Bhagat (jai.bhagat.21@ucl.ac.uk) +- Gonçalo Lopes (g.lopes@neurogears.org) +- Dario Campagner (d.campagner@ucl.ac.uk) +- Chang Huan Lo (changhuan.lo@ucl.ac.uk) ## Citation Policy From eb1b39aa7cf3ae1967167a08443ac6c82a222515 Mon Sep 17 00:00:00 2001 From: lochhh Date: Mon, 4 Nov 2024 16:52:38 +0000 Subject: [PATCH 4/4] Add clone repo as prereq in building docs locally --- src/contributor/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/contributor/index.md b/src/contributor/index.md index 6efc669c..fc1e389a 100644 --- a/src/contributor/index.md +++ b/src/contributor/index.md @@ -159,6 +159,9 @@ For the `aeon_acquisition` Bonsai package, the `make_acquisition_doctree.py` scr This TOC is then used to generate the `src/reference/api/acquisition.rst` file containing the list of modules to be included in the [API reference](target-acquisition-reference). ### Building the documentation locally +To build the documentation locally, first make sure you have cloned the [`aeon_docs` repository](aeon-docs-github:). +The following commands should be run from the root directory of the repository. + Create a `conda` environment with the required dependencies and activate it: ```bash conda create -n aeon_docs python dotnet -c conda-forge