Upgrade documentation to latest design and automation.

Author: guzman-raphael

.github/workflows/development.yaml

@@ -1,9 +1,18 @@
+# a lot of work here
 name: Development
 on:
-  pull_request:
   push:
+    branches:
+      - '**' # every branch
+      - '!gh-pages' # exclude gh-pages branch
+      - '!stage*' # exclude branches beginning with stage
     tags:
-      - "*.*.*"
+      - '\d+\.\d+\.\d+' # only semver tags
+  pull_request:
+    branches:
+      - '**' # every branch
+      - '!gh-pages' # exclude gh-pages branch
+      - '!stage*' # exclude branches beginning with stage
 jobs:
   test-changelog:
     runs-on: ubuntu-latest
@@ -73,7 +82,9 @@ jobs:
           path: dist
           retention-days: 1
   publish-release:
-    if: github.event_name == 'push'
+    if: |
+      github.event_name == 'push' &&
+      startsWith(github.ref, 'refs/tags')
     needs: build
     runs-on: ubuntu-latest
     env:
@@ -146,15 +157,22 @@ jobs:
           asset_path: ${{env.PKG_SDIST_PATH}}
           asset_name: pip-${{env.SDIST_PKG_NAME}}-${{env.PKG_VERSION}}.tar.gz
           asset_content_type: application/gzip
-  # Open Source documentation deploy workflow
-  deploy-docs:
-    if: github.event_name == 'push'
+  publish-docs:
+    if: |
+      github.event_name == 'push' &&
+      startsWith(github.ref, 'refs/tags')
     needs: build
     runs-on: ubuntu-latest
+    env:
+      DOCKER_CLIENT_TIMEOUT: "120"
+      COMPOSE_HTTP_TIMEOUT: "120"
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
-        with:
-          python-version: 3.x
-      - run: pip install mkdocs-material mkdocs-redirects mkdocstrings mkdocstrings-python
-      - run: mkdocs gh-deploy --force --config-file ./docs/mkdocs.yml
+      - name: Deploy docs
+        run: |
+          export MODE=BUILD
+          export PACKAGE=element_array_ephys
+          export UPSTREAM_REPO=https://github.com/${GITHUB_REPOSITORY}.git
+          export HOST_UID=$(id -u)
+          docker compose -f docs/docker-compose.yaml up --exit-code-from docs --build
+          git push origin gh-pages

.gitignore

@@ -101,7 +101,7 @@ ENV/
 .ropeproject
 
 # mkdocs documentation
-/site
+docs/site
 
 # mypy
 .mypy_cache/
@@ -115,4 +115,7 @@ dj_local_conf_old.json
 **/#*#
 **/.#*
 
-docker-compose.y*ml
+docker-compose.y*ml
+
+# include
+!docs/docker-compose.yaml

CHANGELOG.md

@@ -39,10 +39,10 @@ Observes [Semantic Versioning](https://semver.org/spec/v2.0.0.html) standard and
 + Add - Readers for: `SpikeGLX`, `Open Ephys`, `Kilosort`
 + Add - Probe table supporting: Neuropixels probes 1.0 - 3A, 1.0 - 3B, 2.0 - SS, 2.0 - MS
 
-[0.1.4]: https://github.com/datajoint/element-array-ephys/releases/tag/0.1.4
-[0.1.3]: https://github.com/datajoint/element-array-ephys/releases/tag/0.1.3
-[0.1.2]: https://github.com/datajoint/element-array-ephys/releases/tag/0.1.2
-[0.1.1]: https://github.com/datajoint/element-array-ephys/releases/tag/0.1.1
+[0.1.4]: https://github.com/datajoint/element-array-ephys/compare/0.1.3...0.1.4
+[0.1.3]: https://github.com/datajoint/element-array-ephys/compare/0.1.2...0.1.3
+[0.1.2]: https://github.com/datajoint/element-array-ephys/compare/0.1.1...0.1.2
+[0.1.1]: https://github.com/datajoint/element-array-ephys/compare/0.1.0...0.1.1
 [0.1.0]: https://github.com/datajoint/element-array-ephys/compare/0.1.0b0...0.1.0
-[0.1.0b0]: https://github.com/datajoint/element-array-ephys/releases/tag/0.1.0b0
+[0.1.0b0]: https://github.com/datajoint/element-array-ephys/compare/0.1.0a5...0.1.0b0
 [0.1.0a5]: https://github.com/datajoint/element-array-ephys/releases/tag/0.1.0a5

docs/.docker/Dockerfile

@@ -0,0 +1,15 @@
+FROM datajoint/miniconda3:4.10.3-py3.9-alpine
+ARG PACKAGE
+WORKDIR /main
+COPY --chown=anaconda:anaconda ./docs/.docker/apk_requirements.txt ${APK_REQUIREMENTS}
+COPY --chown=anaconda:anaconda ./docs/.docker/pip_requirements.txt ${PIP_REQUIREMENTS}
+RUN \
+    /entrypoint.sh echo "Dependencies installed" && \
+    git config --global user.name "GitHub Action" && \
+    git config --global user.email "action@github.com"&& \
+    git config --global pull.rebase false && \
+    git init
+COPY --chown=anaconda:anaconda ./${PACKAGE} /main/${PACKAGE}
+COPY --chown=anaconda:anaconda ./docs/mkdocs.yaml /main/docs/mkdocs.yaml
+COPY --chown=anaconda:anaconda ./docs/src /main/docs/src
+COPY --chown=anaconda:anaconda ./CHANGELOG.md /main/docs/src/about/changelog.md

docs/.docker/apk_requirements.txt

@@ -0,0 +1 @@
+git

docs/.docker/pip_requirements.txt

@@ -0,0 +1,9 @@
+mkdocs-material
+mkdocs-redirects
+mkdocstrings
+mkdocstrings-python
+mike
+mdx-truly-sane-lists
+mkdocs-gen-files
+mkdocs-literate-nav
+mkdocs-exclude-search

docs/docker-compose-docs-serve.yaml

@@ -0,0 +1,40 @@
+# MODE="LIVE|QA|BUILD" PACKAGE=element_array_ephys UPSTREAM_REPO=https://github.com/datajoint/element-array-ephys.git HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
+#
+# navigate to http://localhost/
+version: "2.4"
+services:
+  docs:
+    build:
+      dockerfile: docs/.docker/Dockerfile
+      context: ../
+      args:
+        - PACKAGE
+    image: ${PACKAGE}-docs
+    environment:
+      - PACKAGE
+      - UPSTREAM_REPO
+      - MODE
+    volumes:
+      - ..:/main
+    user: ${HOST_UID}:anaconda
+    ports:
+      - 80:80
+    command:
+      - sh
+      - -c
+      - |
+        set -e
+        if echo "$${MODE}" | grep -i live &>/dev/null; then
+            mkdocs serve --config-file ./docs/mkdocs.yaml -a 0.0.0.0:80
+        elif echo "$${MODE}" | grep -iE "qa|build" &>/dev/null; then
+            git branch -D gh-pages || true
+            git fetch $${UPSTREAM_REPO} gh-pages:gh-pages || true
+            mike deploy --config-file ./docs/mkdocs.yaml -u $$(grep -oE '\d+\.\d+' /main/$${PACKAGE}/version.py) latest
+            mike set-default --config-file ./docs/mkdocs.yaml latest
+            if echo "$${MODE}" | grep -i qa &>/dev/null; then
+                mike serve --config-file ./docs/mkdocs.yaml -a 0.0.0.0:80
+            fi
+        else
+            echo "Unexpected mode..."
+            exit 1
+        fi

docs/docker-compose.yaml

@@ -1,13 +1,26 @@
+# ---------------------- PROJECT SPECIFIC ---------------------------
+
 site_name: Element Array Ephys
 repo_url: https://github.com/datajoint/element-array-ephys
 repo_name: datajoint/element-array-ephys
-docs_dir: ./src/
+nav:
+  - Element Array Ephys: getting_started.md
+  - Getting Started: getting_started.md
+  - Concepts: concepts.md
+  - Tutorials: tutorials.md
+  - About:
+    - Changelog: about/changelog.md
+  - API: api/ # defer to gen-files + literate-nav
 
+# ---------------------------- STANDARD -----------------------------
+
+edit_uri: ./edit/main/docs/src
+docs_dir: ./src
 theme:
   name: material
-  custom_dir: overrides
-  logo: assets/elements-logo-black.png
-  favicon: assets/elements-logo.png
+  custom_dir: src/.overrides
+  logo: assets/images/project-logo-black.png
+  favicon: assets/images/project-logo-color.png
   features:
     - toc.integrate
   palette:
@@ -21,38 +34,41 @@ theme:
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
-
-nav:
-  - Element Array Ephys: getting_started/index.md
-  - Getting Started:
-      - Installation: getting_started/index.md
-      - Set Up: getting_started/setup.md
-  - Tutorials: tutorials.md
-  - Concepts: concepts.md
-  - About: about.md
-  - API: api.md
-
 plugins:
   - search
   - redirects:
       redirect_maps:
-        "index.md": "getting_started/index.md"
+        "index.md": "getting_started.md"
   - mkdocstrings:
       default_handler: python
-
+  - gen-files:
+      scripts:
+      - ./src/api/make_pages.py
+  - literate-nav:
+      nav_file: navigation.md
+  - exclude-search:
+      exclude:
+        - "*/navigation.md"
 markdown_extensions:
   - attr_list
   - toc:
       permalink: true
   - pymdownx.emoji:
       options:
         custom_icons:
-          - overrides/.icons
-
+          - .overrides/.icons
+  - mdx_truly_sane_lists
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
 extra:
   generator: false # Disable watermark
+  version:
+    provider: mike
   social:
-    - icon: datajoint/dj-logo-white
+    - icon: datajoint/company-logo
       link: https://www.datajoint.com/
     - icon: fontawesome/brands/slack
       link: https://datajoint.slack.com
@@ -66,6 +82,5 @@ extra:
       link: https://stackoverflow.com/questions/tagged/datajoint
     - icon: fontawesome/brands/youtube
       link: https://www.youtube.com/channel/UCdeCuFOTCXlVMRzh6Wk-lGg
-
 extra_css:
-  - stylesheets/extra.css
+  - assets/stylesheets/extra.css