Merge pull request #233 from matthewwardrop/add_documentation_versioning

Author: matthewwardrop

.github/workflows/publish.yml

@@ -5,23 +5,30 @@ on:
     tags:
       - "v*"
 
+permissions:
+  contents: write
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v1
-    - name: Set up Python
-      uses: actions/setup-python@v1
-      with:
-        python-version: '3.9'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install hatch
-    - name: Build and publish
-      env:
-        HATCH_INDEX_USER: __token__
-        HATCH_INDEX_AUTH: ${{ secrets.PYPI_PUBLISH_TOKEN }}
-      run: |
-        hatch build
-        hatch publish
+      - uses: actions/checkout@v1
+      - name: Set up Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: "3.9"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+      - name: Build and publish
+        env:
+          HATCH_INDEX_USER: __token__
+          HATCH_INDEX_AUTH: ${{ secrets.PYPI_PUBLISH_TOKEN }}
+        run: |
+          hatch build
+          hatch publish
+      - name: Build and deploy docs
+        run: |
+          VERSION=$(echo "${{ github.ref_name }}" | sed -E s/\.[0-9]+$/\.x/)
+          hatch run docs:deploy "$VERSION" latest

.github/workflows/publish_docs.yml

@@ -6,7 +6,7 @@ on:
       - main
 
 permissions:
-    contents: write
+  contents: write
 
 jobs:
   build:
@@ -29,7 +29,11 @@ jobs:
           path: .cache
           restore-keys: |
             mkdocs-material-
+      - name: Install hatch
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
       - name: Build and Deploy docs.
         run: |
-          pip install -r docsite/requirements.txt
-          mkdocs gh-deploy -v --config-file docsite/mkdocs.yml --force
+          git pull origin gh-pages
+          hatch run docs:deploy dev

docsite/mkdocs.yml

@@ -1,26 +1,26 @@
 site_name: Formulaic
 nav:
   - Getting Started:
-    - Introduction: index.md
-    - What are formulas?: formulas.md
-    - Installation: installation.md
-    - Migrating from Patsy/R: migration.md
-    - Changelog: changelog.md
+      - Introduction: index.md
+      - What are formulas?: formulas.md
+      - Installation: installation.md
+      - Migrating from Patsy/R: migration.md
+      - Changelog: changelog.md
   - User Guides:
-    - Introduction: guides/index.md
-    - Quickstart: guides/quickstart.ipynb
-    - How it works: guides/formulae.ipynb
-    - Handling Missing Data: guides/missing_data.ipynb
-    - Formula Grammar: guides/grammar.md
-    - Model Specs: guides/model_specs.ipynb
-    - Transforms: guides/transforms.ipynb
-    - Categorical Encoding: guides/contrasts.ipynb
-    - Spline Encoding: guides/splines.ipynb
-    - Using with existing libraries: guides/integration.ipynb
+      - Introduction: guides/index.md
+      - Quickstart: guides/quickstart.ipynb
+      - How it works: guides/formulae.ipynb
+      - Handling Missing Data: guides/missing_data.ipynb
+      - Formula Grammar: guides/grammar.md
+      - Model Specs: guides/model_specs.ipynb
+      - Transforms: guides/transforms.ipynb
+      - Categorical Encoding: guides/contrasts.ipynb
+      - Spline Encoding: guides/splines.ipynb
+      - Using with existing libraries: guides/integration.ipynb
   - Developer Guides:
-    - Introduction: dev/index.md
-    - Integration: dev/integration.md
-    - Extensions: dev/extensions.md
+      - Introduction: dev/index.md
+      - Integration: dev/integration.md
+      - Extensions: dev/extensions.md
 theme:
   name: material
   font:
@@ -45,3 +45,7 @@ plugins:
   - mkdocs-jupyter
 extra_css:
   - assets/styles.css
+extra:
+  version:
+    alias: true
+    provider: mike

docsite/overrides/base.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  This documentation is for an older version of Formulaic.
+  <a href="{{ '../' ~ base_url }}"> 
+    <strong>Click here to go to latest version.</strong>
+  </a>
+{% endblock %}

docsite/requirements.in

@@ -1,11 +1,26 @@
 #
-# This file is autogenerated by pip-compile with Python 3.10
-# by the following command:
+# This file is autogenerated by hatch-pip-compile with Python 3.12
 #
-#    pip-compile --output-file=requirements.txt requirements.in
+# - mike
+# - mkdocs
+# - mkdocs-jupyter
+# - mkdocs-material
+# - mkdocs-material-extensions
+# - pymdown-extensions
+# - pygments
+# - astor>=0.8; python_version < "3.9"
+# - cached-property>=1.3.0; python_version < "3.8"
+# - graphlib-backport>=1.0.0; python_version < "3.9"
+# - interface-meta>=1.2.0
+# - numpy>=1.16.5
+# - pandas>=1.0
+# - scipy>=1.6
+# - typing-extensions>=4.2.0
+# - wrapt>=1.0; python_version < "3.13"
+# - wrapt>=1.17.0rc1; python_version >= "3.13"
 #
 
-asttokens==2.4.1
+asttokens==3.0.0
     # via stack-data
 attrs==24.2.0
     # via
@@ -17,7 +32,7 @@ beautifulsoup4==4.12.3
     # via nbconvert
 bleach==6.2.0
     # via nbconvert
-certifi==2024.8.30
+certifi==2024.12.14
     # via requests
 charset-normalizer==3.4.0
     # via requests
@@ -27,30 +42,35 @@ colorama==0.4.6
     # via mkdocs-material
 comm==0.2.2
     # via ipykernel
-debugpy==1.8.8
+debugpy==1.8.11
     # via ipykernel
 decorator==5.1.1
     # via ipython
 defusedxml==0.7.1
     # via nbconvert
-exceptiongroup==1.2.2
-    # via ipython
 executing==2.1.0
     # via stack-data
-fastjsonschema==2.20.0
+fastjsonschema==2.21.1
     # via nbformat
 ghp-import==2.1.0
     # via mkdocs
 idna==3.10
     # via requests
+importlib-metadata==8.5.0
+    # via mike
+importlib-resources==6.4.5
+    # via mike
+interface-meta==1.3.0
+    # via hatch.envs.docs
 ipykernel==6.29.5
     # via mkdocs-jupyter
-ipython==8.29.0
+ipython==8.30.0
     # via ipykernel
 jedi==0.19.2
     # via ipython
 jinja2==3.1.4
     # via
+    #   mike
     #   mkdocs
     #   mkdocs-material
     #   nbconvert
@@ -71,7 +91,7 @@ jupyter-core==5.7.2
     #   nbformat
 jupyterlab-pygments==0.3.0
     # via nbconvert
-jupytext==1.16.4
+jupytext==1.16.5
     # via mkdocs-jupyter
 markdown==3.7
     # via
@@ -99,26 +119,29 @@ mergedeep==1.3.4
     # via
     #   mkdocs
     #   mkdocs-get-deps
+mike==2.1.3
+    # via hatch.envs.docs
 mistune==3.0.2
     # via nbconvert
 mkdocs==1.6.1
     # via
-    #   -r requirements.in
+    #   hatch.envs.docs
+    #   mike
     #   mkdocs-jupyter
     #   mkdocs-material
 mkdocs-get-deps==0.2.0
     # via mkdocs
 mkdocs-jupyter==0.25.1
-    # via -r requirements.in
-mkdocs-material==9.5.44
+    # via hatch.envs.docs
+mkdocs-material==9.5.48
     # via
-    #   -r requirements.in
+    #   hatch.envs.docs
     #   mkdocs-jupyter
 mkdocs-material-extensions==1.3.1
     # via
-    #   -r requirements.in
+    #   hatch.envs.docs
     #   mkdocs-material
-nbclient==0.10.0
+nbclient==0.10.1
     # via nbconvert
 nbconvert==7.16.4
     # via mkdocs-jupyter
@@ -129,6 +152,11 @@ nbformat==5.10.4
     #   nbconvert
 nest-asyncio==1.6.0
     # via ipykernel
+numpy==2.2.0
+    # via
+    #   hatch.envs.docs
+    #   pandas
+    #   scipy
 packaging==24.2
     # via
     #   ipykernel
@@ -137,6 +165,8 @@ packaging==24.2
     #   nbconvert
 paginate==0.5.7
     # via mkdocs-material
+pandas==2.2.3
+    # via hatch.envs.docs
 pandocfilters==1.5.1
     # via nbconvert
 parso==0.8.4
@@ -159,28 +189,36 @@ pure-eval==0.2.3
     # via stack-data
 pygments==2.18.0
     # via
-    #   -r requirements.in
+    #   hatch.envs.docs
     #   ipython
     #   mkdocs-jupyter
     #   mkdocs-material
     #   nbconvert
 pymdown-extensions==10.12
     # via
-    #   -r requirements.in
+    #   hatch.envs.docs
     #   mkdocs-material
+pyparsing==3.2.0
+    # via mike
 python-dateutil==2.9.0.post0
     # via
     #   ghp-import
     #   jupyter-client
+    #   pandas
+pytz==2024.2
+    # via pandas
 pyyaml==6.0.2
     # via
     #   jupytext
+    #   mike
     #   mkdocs
     #   mkdocs-get-deps
     #   pymdown-extensions
     #   pyyaml-env-tag
 pyyaml-env-tag==0.1
-    # via mkdocs
+    # via
+    #   mike
+    #   mkdocs
 pyzmq==26.2.0
     # via
     #   ipykernel
@@ -193,23 +231,21 @@ regex==2024.11.6
     # via mkdocs-material
 requests==2.32.3
     # via mkdocs-material
-rpds-py==0.21.0
+rpds-py==0.22.3
     # via
     #   jsonschema
     #   referencing
-six==1.16.0
-    # via
-    #   asttokens
-    #   python-dateutil
+scipy==1.14.1
+    # via hatch.envs.docs
+six==1.17.0
+    # via python-dateutil
 soupsieve==2.6
     # via beautifulsoup4
 stack-data==0.6.3
     # via ipython
 tinycss2==1.4.0
     # via nbconvert
-tomli==2.1.0
-    # via jupytext
-tornado==6.4.1
+tornado==6.4.2
     # via
     #   ipykernel
     #   jupyter-client
@@ -225,9 +261,13 @@ traitlets==5.14.3
     #   nbconvert
     #   nbformat
 typing-extensions==4.12.2
-    # via ipython
+    # via hatch.envs.docs
+tzdata==2024.2
+    # via pandas
 urllib3==2.2.3
     # via requests
+verspec==0.1.0
+    # via mike
 watchdog==6.0.0
     # via mkdocs
 wcwidth==0.2.13
@@ -236,3 +276,7 @@ webencodings==0.5.1
     # via
     #   bleach
     #   tinycss2
+wrapt==1.17.0 ; python_version < "3.13"
+    # via hatch.envs.docs
+zipp==3.21.0
+    # via importlib-metadata