Merge pull request #2 from lochhh/update-docs

Update docs

.github/workflows/docs_build_and_deploy.yml

@@ -0,0 +1,103 @@
+name: Docs
+
+# Generate the documentation on all merges to main, all pull requests, or by
+# manual workflow dispatch. The build job can be used as a CI check that the
+# docs still build successfully. The deploy job only runs when a tag is
+# pushed and actually moves the generated html to the gh-pages branch
+# (which triggers a GitHub pages deployment).
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - '*'
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build_sphinx_docs:
+    name: Build Sphinx Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: false # Disable automatic checkout of all submodules
+
+      - name: Checkout public submodules # Skip aeon_experiments
+        run: |
+          git submodule sync
+          git submodule update --init aeon_acquisition
+          git submodule update --init aeon_analysis
+          git submodule update --init aeon_blog
+          git submodule update --init aeon_mecha
+        
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Upgrade pip
+        shell: bash
+        run: |
+          # install pip=>20.1 to use "pip cache dir"
+          python3 -m pip install --upgrade pip
+
+      - name: Get pip cache dir
+        shell: bash
+        id: pip-cache
+        run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.pip-cache.outputs.dir }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        shell: bash
+        run: python3 -m pip install -r ./requirements.txt
+
+      # temporarily disabled until we fix broken links
+      # - name: Check links
+      #  shell: bash
+      #  run: make linkcheck
+
+      # needs to have sphinx.ext.githubpages in conf.py extensions list
+      - name: Building documentation
+        shell: bash
+        run: make html
+
+      - name: Upload the content for deployment
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: ./docs/
+
+  deploy_sphinx_docs:
+    name: Deploy Sphinx Docs
+    needs: build_sphinx_docs
+    permissions:
+      contents: write
+    if: github.event_name == 'push' && github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Clear previous build if present
+        shell: bash
+        run: rm -rf ./docs/
+
+      - name: Download the content for deployment
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+          path: ./docs/
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/html/

.gitignore

@@ -0,0 +1,4 @@
+# Sphinx documentation
+docs/
+src/api/
+src/api.rst

.gitmodules

@@ -1,15 +1,20 @@
 [submodule "aeon_mecha"]
 	path = aeon_mecha
 	url = https://github.com/SainsburyWellcomeCentre/aeon_mecha
+	branch = main
 [submodule "aeon_analysis"]
 	path = aeon_analysis
 	url = https://github.com/SainsburyWellcomeCentre/aeon_analysis
+	branch = main
 [submodule "aeon_blog"]
 	path = aeon_blog
 	url = https://github.com/SainsburyWellcomeCentre/aeon_blog
+	branch = main
 [submodule "aeon_experiments"]
 	path = aeon_experiments
 	url = https://github.com/SainsburyWellcomeCentre/aeon_experiments
+	branch = main
 [submodule "aeon_acquisition"]
 	path = aeon_acquisition
 	url = https://github.com/SainsburyWellcomeCentre/aeon_acquisition
+	branch = main

Makefile

@@ -14,7 +14,17 @@ help:
 
 .PHONY: help Makefile
 
+# Generate the API documentation
+api.rst:
+	python make_api_doctree.py
+
+# Remove all generated files
+clean:
+	rm -rf ./docs
+	rm -f ./src/api.rst
+	rm -rf ./src/api
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
+%: Makefile api.rst
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)