Add guidelines to Contributing Documentation

make_mecha_doctree.py

@@ -1,4 +1,6 @@
 import os
+from pathlib import Path
+
 
 # modules to ignore in the api doc
 ignore_modules = [
@@ -12,34 +14,23 @@ def make_mecha_doctree():
     Create a doctree of all modules in aeon_mecha/aeon.
     """
     doctree = ""
-    api_path = os.path.join(".", "aeon_mecha", "aeon")
-    for root, dirs, files in os.walk(api_path):
-        # remove leading "./"
-        root = root[2:]
-        for file in sorted(files):
-            if file.endswith(".py") and not file.startswith("_"):
-                # convert file path to module name
-                full = os.path.join(root, file)
-                full = full[:-3].replace(os.sep, ".")
-                full = (".").join(full.split(".")[1:])
-                ignore = False
-                for ignore_module in ignore_modules:
-                    if full.startswith(ignore_module):
-                        ignore = True
-                        break
-                if not ignore:
-                    doctree += f"    {full}\n"
-
-    # get the api doc header
-    with open("src/_templates/api_mecha_head.rst", "r") as f:
-        api_head = f.read()
-
-    # write file for api doc with header + doctree
-    output_dir = "./src/reference/api"
-    os.makedirs(output_dir, exist_ok=True)
-
-    with open(os.path.join(output_dir, "mecha.rst"), "w") as f:
-        f.write("..\n  This file is auto-generated.\n\n")
+    api_path = Path("aeon_mecha") / "aeon"
+    for path in sorted(api_path.rglob("*.py")):
+        if path.name.startswith("_"):
+            continue
+        # Convert file path to module name
+        full = str(path.with_suffix("")).replace(os.sep, ".")
+        full = ".".join(full.split(".")[1:])
+        if not any(full.startswith(ignore_module) for ignore_module in ignore_modules):
+            doctree += f"   {full}\n"
+    # Get the main page header
+    api_head_path = Path("src") / "_templates" / "api_mecha_head.rst"
+    api_head = api_head_path.read_text()
+    # Write main page with header and doc tree
+    output_dir = Path("src") / "reference" / "api"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output_file = output_dir / "mecha.rst"
+    with output_file.open("w") as f:
         f.write(api_head)
         f.write(doctree)
 

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 <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])
@@ -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)
 
@@ -158,18 +57,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
 

src/_templates/api_mecha_head.rst

@@ -1,12 +1,15 @@
+..
+  This file is auto-generated.
+
 .. _target-mecha-reference:
 
 ``aeon_mecha``
 ==============
 
 .. toctree::
-    :caption: aeon_mecha API
-    :maxdepth: 1
+   :caption: aeon_mecha API
+   :maxdepth: 1
 
 .. autosummary::
-    :toctree: mecha
+   :toctree: mecha
 

src/conf.py

@@ -139,10 +139,10 @@ def get_current_release_tag():
 # 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,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 html_css_files = [
     "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css",
-    "css/custom.css",	
+    "css/custom.css",
 ]
 
 # linkcheck will skip checking these URLs entirely
@@ -164,14 +164,18 @@ 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-analysis-github": "https://github.com/SainsburyWellcomeCentre/aeon_analysis/{{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}}",
 }