Add release versioning with mike (#409)

.github/workflows/build_docs.yml

@@ -0,0 +1,54 @@
+name: "Build docs and deploy"
+on:
+  push:
+    branches:
+      - main
+  release:
+    types: [ published ]
+
+jobs:
+  docs:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        lfs: false
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.10'
+
+    - name: Cache dependency
+      id: cache-dependencies
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip
+
+    - name: Install jaxley and dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install .[doc]
+    - name: convert notebooks to markdown
+      run: |
+        cd docs
+        jupyter nbconvert --to markdown ../examples/*.ipynb --output-dir docs/examples/
+        jupyter nbconvert --to markdown ../tutorials/*.ipynb --output-dir docs/tutorials/
+    - name: Configure Git user for bot
+      run: |
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+    - name: Build and deploy dev documentation upon push to main
+      if: ${{ github.event_name == 'push' }}
+      run: |
+        cd docs
+        mike deploy dev --push
+    - name: Build and deploy the lastest documentation upon new release
+      if: ${{ github.event_name == 'release' }}
+      run: |
+        cd docs
+        mike deploy ${{ github.event.release.name }} latest -u --push

.gitignore

@@ -1,6 +1,4 @@
 # Project specific
-/docs/docs/tutorial/*
-/docs/docs/examples/*
 /docs/site/*
 **/.DS_Store
 

docs/mkdocs.yml

@@ -39,10 +39,16 @@ theme:
   logo: logo_white.png
   collapse_navigation: False
 
+extra:
+  version:
+    provider: mike
+
 markdown_extensions:
   - extra
   - smarty
   - admonition
+  - attr_list
+  - md_in_html
   - codehilite:
       guess_lang: false
   - toc:
@@ -57,8 +63,7 @@ markdown_extensions:
   - pymdownx.caret
   - pymdownx.critic
   - pymdownx.details
-  - pymdownx.emoji:
-      emoji_generator: !!python/name:pymdownx.emoji.to_svg
+  - pymdownx.emoji
   - pymdownx.inlinehilite
   - pymdownx.magiclink
   - pymdownx.mark
@@ -71,6 +76,7 @@ markdown_extensions:
 
 plugins:
   - search
+  - mike
   - mkdocstrings:
       default_handler: python
       handlers:

pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools>=45", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "jaxley"
+name = "Jaxley"
 version = "0.1.2"
 description = "Differentiable neuron simulations."
 authors = [
@@ -35,15 +35,20 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = [
-    "black",
-    "isort",
-    "jupyter",
+doc = [
+    "jupyter_contrib_nbextensions",
+    "notebook <= 6.4.12",
+    "traitlets <= 5.9.0",
+    "ipython <= 8.9.0",
     "mkdocs",
     "mkdocs-material",
     "markdown-include",
     "mkdocs-redirects",
     "mkdocstrings[python]>=0.18",
+]
+dev = [
+    "black",
+    "isort",
     "neuron",
     "pytest",
     "pyright",