enable github pages for website (#3)

* enable github pages for website

* dont execute notebooks in docs

* add local install to docs actions

Author: mdtanker

.github/workflows/docs_preview.yml

@@ -0,0 +1,72 @@
+name: Docs Preview
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - edited
+      - closed
+    branches:
+      - "main"
+  workflow_dispatch:
+
+concurrency: preview-${{github.ref}}
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    # only run if from the same repository, not a fork
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: write
+      pull-requests: write
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      # Checkout current git repository
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      # setup python env
+      - uses: actions/setup-python@v5
+        if: github.event.action != 'closed' # Skip the build if the PR has been closed; just run the clean up steps
+        with:
+          python-version: "3.x"
+
+      - uses: prefix-dev/setup-pixi@v0.9.2
+        with:
+          pixi-version: v0.55.0
+          environments: >-
+            docs
+
+      - id: install_local
+        run: pip install --no-deps -e .
+
+      - id: install_pandoc
+        run: sudo apt-get install pandoc
+
+      # Make API docs
+      - name: Make API docs
+        if: github.event.action != 'closed'
+        run: pixi run api
+
+      # Build the documentation
+      - name: Build the documentation
+        if: github.event.action != 'closed'
+        run: pixi run docs
+
+      # Deploy the preview of the docs
+      - name: Deploy Preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: docs/_build/html
+          preview-branch: gh-pages
+          # custom-url:
+          umbrella-dir: pr-preview
+          action: auto
+          deploy-repository: ${{ github.repository }}
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/documentation.yml

@@ -0,0 +1,58 @@
+name: documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+# This job installs dependencies, builds the html, and pushes it to gh-pages
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }} # only run one of these jobs at a time
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      # Checkout current git repository
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      # setup python env
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - uses: prefix-dev/setup-pixi@v0.9.2
+        with:
+          pixi-version: v0.55.0
+          environments: >-
+            docs
+
+      - id: install_local
+        run: pip install --no-deps -e .
+
+      - id: install_pandoc
+        run: sudo apt-get install pandoc
+
+      # Make API docs
+      - name: Make API docs
+        run: pixi run api
+
+      # Build the documentation
+      - name: Build the documentation
+        run: pixi run docs
+
+      # Deploy the HTML to gh-pages branch
+      - name: GitHub Pages action
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html
+          publish_branch: gh-pages
+          force_orphan: true

docs/conf.py

@@ -61,7 +61,7 @@
 # add_function_parentheses = False
 
 
-nbsphinx_execute = "auto"
+nbsphinx_execute = "never"
 
 nbsphinx_execute_arguments = [
     "--InlineBackend.figure_formats={'png2x'}",

pixi.lock

@@ -76,7 +76,8 @@ nbsphinx = "*"
 sphinx-autobuild = ">=2024.10.3,<2025"
 
 [tool.pixi.feature.docs.tasks]
-docs = "sphinx-autobuild --open-browser -n -T -b html docs docs/_build/html"
+docs_interactive = "sphinx-autobuild --open-browser -n -T -b html docs docs/_build/html"
+docs = "sphinx-build -n -T -b html docs docs/_build/html"
 api = "sphinx-apidoc -o docs/api/ --module-first --no-toc --force src/synthetic_bathymetry_inversion"