Add aeon_mecha installation docs (#22)

* Update placeholder text

* Add mailto links

* Add aeon_mecha setup instructions

* Resolve submodule conflict in �eon_analysis

* Add code copy button

* Fix typo

* Add setup instructions and examples

* Use myst-nb instead of nbsphinx

* Update URLs

* Use myst to parse markdown

* Update docstring

* Move style doc guidelines

* Rename About

* Ignore internal wiki during linkcheck

* Standardise target names

* Copy example notebooks to src

* Update remote setup guide

* Update remote dev description

.gitignore

@@ -1,4 +1,5 @@
 # Sphinx documentation
 docs/
 src/reference/api/
-src/reference/api.rst
+src/reference/api.rst
+src/user/**/*_copy*

.gitmodules

@@ -5,7 +5,7 @@
 [submodule "aeon_analysis"]
 	path = aeon_analysis
 	url = https://github.com/SainsburyWellcomeCentre/aeon_analysis
-	branch = main
+	branch = api-notebooks
 [submodule "aeon_blog"]
 	path = aeon_blog
 	url = https://github.com/SainsburyWellcomeCentre/aeon_blog

Makefile

@@ -12,19 +12,23 @@ BUILDDIR      = docs
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+$(SOURCEDIR)/reference/api.rst:
+	@echo "Generating API documentation..."
+	@python make_api_doctree.py
 
-# Generate the API documentation
-api.rst:
-	python make_api_doctree.py
+copy-examples:
+	@echo "Copying example notebooks to 'src'..."
+	@python copy_examples_to_src.py
 
-# Remove all generated files
 clean:
-	rm -rf ./docs
-	rm -f ./src/reference/api.rst
-	rm -rf ./src/reference/api
+	@echo "Removing auto-generated files under 'docs' and 'src'..."
+	@rm -rf $(BUILDDIR)
+	@rm -f $(SOURCEDIR)/reference/api.rst
+	@rm -rf $(SOURCEDIR)/reference/api
+
+.PHONY: help Makefile copy-examples
 
 # Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile api.rst
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile $(SOURCEDIR)/reference/api.rst copy-examples
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

copy_examples_to_src.py

@@ -0,0 +1,34 @@
+import os
+import shutil
+
+
+def copy_ipynb_files(src_dirs: str | list[str], dst_dir: str) -> None:
+    """
+    Copy all ``.ipynb`` files from ``src_dirs`` to ``dst_dir``.
+
+    Args:
+        src_dirs (str | list[str]): A list of directories or a single directory.
+        dst_dir (str): The destination directory.
+    """
+    if not os.path.exists(dst_dir):
+        os.makedirs(dst_dir)
+
+    if not isinstance(src_dirs, list):
+        src_dirs = [src_dirs]
+
+    for src_dir in src_dirs:
+        for file_name in os.listdir(src_dir):
+            if file_name.endswith(".ipynb"):
+                name, extension = os.path.splitext(file_name)
+                # Append "_copy" to the name
+                new_file_name = f"{name}_copy{extension}"
+                shutil.copy(
+                    os.path.join(src_dir, file_name),
+                    os.path.join(dst_dir, new_file_name),
+                )
+
+
+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)

make.bat

@@ -12,9 +12,12 @@ set BUILDDIR=docs
 
 if "%1" == "" goto help
 
-echo "Building api docs..."
+echo "Building API docs..."
 python make_api_doctree.py
 
+echo "Copying example notebooks into src..."
+python copy_examples_to_src.py
+
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.

make_api_doctree.py

@@ -9,7 +9,7 @@
 
 def make_api_doctree():
     """
-    Create a doctree of all modules in aeon_mecha/aeon
+    Create a doctree of all modules in aeon_mecha/aeon.
     """
     doctree = ""
 

readme.md

@@ -80,19 +80,19 @@ If you are interested in joining this project, please contact the [project maint
 
 Below are the required sets of credentials for Project Aeon's members: 
 
-- Microsoft Teams: contact Jai Bhagat, Goncalo Lopes, or Dario Campagner
-- SWC Github organization: contact SWC Helpdesk ([email protected])
-- SWC Github 'aeon' project: contact Jai Bhagat or Goncalo Lopes
-- SWC HPC: contact SWC Helpdesk
-- 'aeon' HPC Linux group: contact SWC Helpdesk
-- Datajoint database username: contact Thinh Nguyen ([email protected])
+- 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])
+- SWC Github `aeon` project: contact [Jai Bhagat](mailto:[email protected]) or [Gonçalo Lopes](mailto:[email protected])
+- SWC HPC: contact [SWC Helpdesk](mailto:[email protected])
+- `aeon` HPC Linux group: contact [SWC Helpdesk](mailto:[email protected])
+- Datajoint database username: contact [Thinh Nguyen](mailto:[email protected])
 
-To be granted these credentials, please send a single email to all contact parties requesting this access.
+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.
+> You must be an SWC Github `aeon` project member to view some of these repositories.
 
 ### [aeon_mecha](https://github.com/SainsburyWellcomeCentre/aeon_mecha)
 

requirements.txt

@@ -1,11 +1,12 @@
-# mininum dependencies to build aeon_mecha docs
+# minimum dependencies to build aeon_mecha docs
 dotmap
 matplotlib
 opencv-python
 pandas 
 
-myst-parser
 linkify-it-py
-sphinx-design
+myst-nb
+pydata-sphinx-theme
 sphinx-autodoc-typehints
-pydata-sphinx-theme
+sphinx-copybutton
+sphinx-design

src/_templates/api_head.rst

@@ -1,4 +1,4 @@
-.. _api:
+.. _target-api-reference:
 
 API Reference
 =============

src/about/index.md

@@ -1,5 +1,5 @@
 (target-about)=
-# About Project Aeon
+# About
 
 Development of Project Aeon is supported by... 
 

src/conf.py

@@ -65,8 +65,9 @@ def get_current_release_tag():
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_autodoc_typehints",
-    "myst_parser",
+    "myst_nb",
     "sphinx_design",
+    "sphinx_copybutton",
 ]
 
 # Configure the myst parser to enable cool markdown features
@@ -81,6 +82,12 @@ def get_current_release_tag():
 # Automatically add anchors to markdown headings
 myst_heading_anchors = 3
 
+# Set the Markdown format to myst
+myst_render_markdown_format = "myst"
+
+# Disable notebook execution
+nb_execution_mode = "off"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -134,7 +141,7 @@ def get_current_release_tag():
 
 # linkcheck will skip checking these URLs entirely
 linkcheck_ignore = [
-    "https://github.com/SainsburyWellcomeCentre/aeon_experiments",  # This is currently a private repository
+    r"https://wiki\.ucl\.ac\.uk/.*",  # This is the UCL internal wiki
 ]
 
 # linkcheck will treat redirections from these source URI:canonical URI
@@ -153,4 +160,5 @@ 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}}",
+    "niu-howto": "https://howto.neuroinformatics.dev/programming/SSH-SWC-cluster#{{fragment}}",
 }

src/contributor/index.md

@@ -27,7 +27,7 @@ We use Github Actions to run CI. We run unit tests on Github Virtual Machines on
 
 ## Contributing
 
-Each repository roughly follows the [github flow](https://docs.github.com/en/get-started/quickstart/github-flow) (which is adapted from the more general 
+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)). 
 
 In brief, each of our repos has 'main' and 'prod' branches. Feature and bug fix branches are branched off of 'main', with Pull Requests sent back into 'main'. 'main' contains the full commit history of the project, up to the latest stable commit. Upon merges into 'main', a squash merge is performed into 'prod', such that 'prod' contains an abbreviated commit history of the project, with commits pertaining only to Pull Request merges. 'prod' thus serves as a "production" branch to allow for easier readability of project history and easier reversion of uncaught bug commits. At certain agreed upon timepoints we create "stable releases" (available in the "releases" section of the repository) which serve as a snapshot of the code at the time, version numbered according to [SemVer](semver:).
@@ -36,19 +36,12 @@ When contributing to any repository, the change to be made should first be discu
 
 All pull requests will be reviewed by the [project maintainers](target-project-maintainers). Minimally, maintainers should follow the below steps when reviewing pull requests:
 
-1) Ensure new code adheres to the [style and documentation guidelines](#style-and-documentation-guidelines), is covered by a test, and passes a build test. These can all be checked via CI.
+1) Ensure new code adheres to the [style and documentation guidelines](target-style-doc-guidelines), is covered by a test, and passes a build test. These can all be checked via CI.
 
 2) As necessary, ensure `changelog`, `readme`, config and doc files are updated.
 
 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)
 
-## Style and Documentation Guidelines
-
-Please see our [style and documentation guidelines](target-style-doc-guidelines).
-
-We also believe in the [readme manifesto](http://thinkinghard.com/blog/TheREADMEManifesto.html), which says that `readme` files should provide at least a general description that covers _all_ of a project's files, and that one `readme` per subdirectory is generally good practice.
-
-
 :::{toctree}
 :maxdepth: 1
 :hidden:

src/contributor/style_and_doc_guidelines.md

@@ -3,7 +3,7 @@
 
 The purpose of this document is to establish Project Aeon code style and documentation guidelines.
 
-We generally adhere to [pep8](python-pep:0008), [pep257](python-pep:0257), and [google's style guide](https://google.github.io/styleguide/pyguide.html) for code and docstring style guidelines. We run black, ruff, and pyright to format our Python code, the config settings for which can be found in a repository's `pyproject.toml`.
+We generally adhere to [pep8](python-pep:0008), [pep257](python-pep:0257), and [google's style guide](https://google.github.io/styleguide/pyguide.html) for code and docstring style guidelines. We run black, ruff, and pyright to format our Python code, the config settings for which can be found in a repository's `pyproject.toml`. We also believe in the [readme manifesto](https://www.thinkinghard.com/blog/TheREADMEManifesto), which says that `readme` files should provide at least a general description that covers _all_ of a project's files, and that one `readme` per subdirectory is generally good practice.
 
 ## General Guidelines
 
@@ -55,7 +55,7 @@ We generally adhere to [pep8](python-pep:0008), [pep257](python-pep:0257), and [
   - Prefix 'n' is used for integer values e.g. `n_items`.
   - Suffix 'num' is used for referring to a particular instance e.g. `item_num`.
   - Suffices that indicate unit measurement are used when using multiple units e.g. `wheel_deg` and `wheel_mm`.
-  - Re-use of variable names (i.e. mutation) is generally avoided.
+  - Reuse of variable names (i.e. mutation) is generally avoided.
   - Variables across related files which share names should share meanings.
 * Comments are for explaining _what_ a particular chunk of code does when it may be unintuitive, not for explaining exactly _how_ the code does what it does.
 * Block comments read as a narrative.