Merge pull request #195 from thorinaboenke/feature/github_pages

Feature/GitHub pages

Author: thorinaboenke

.github/workflows/publish-docs.yml

@@ -0,0 +1,42 @@
+name: Publish Docs
+on:
+  push:
+    branches:
+      - main
+      - development
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Crucial: sphinx-multiversion needs git history to find tags/branches
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Build Multi-version Docs
+        run: |
+          uv run --with-requirements docs/requirements.txt sphinx-multiversion docs/source docs/build/html
+
+
+      - name: Create Redirect Root
+        run: |
+          # Redirects root URL (repo.io/) to the main branch docs (repo.io/main/)
+          echo '<meta http-equiv="refresh" content="0; url=main/index.html">' > docs/build/html/index.html
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: docs/build/html

Jenkinsfile

@@ -2,3 +2,4 @@ sphinx
 sphinx_rtd_theme
 sphinx_toolbox
 myst_parser
+sphinx-multiversion

docs/requirements.txt

@@ -0,0 +1,19 @@
+{% if versions %}
+<div class="rst-versions" role="note" aria-label="versions">
+    <span class="rst-current-version">
+        <span class="fa fa-book"> Version</span>
+        {{ current_version.name }}
+    </span>
+
+    <div class="rst-other-versions">
+        <dl>
+            <dt>Versions</dt>
+            {% for v in versions %}
+            <dd>
+                <a href="{{ v.url }}">{{ v.name }}</a>
+            </dd>
+            {% endfor %}
+        </dl>
+    </div>
+</div>
+{% endif %}

docs/source/_templates/layout.html

@@ -18,7 +18,17 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'myst_parser', 'sphinx_toolbox.confval']
+extensions = [
+    'sphinx_multiversion',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'myst_parser',
+    'sphinx_toolbox.confval']
+
+# Configure what branches/tags to include
+smv_tag_whitelist = r'^v?\d+\.\d+\.\d+$'  # Includes tags like v1.0.0
+smv_branch_whitelist = r'^(main|development)$'        # Includes the main branch
+smv_remote_whitelist = None      # Only look at origin
 
 templates_path = ['_templates']
 exclude_patterns = []  # type: ignore
@@ -34,3 +44,16 @@
     'navigation_depth': 2,
     'collapse_navigation': True,
 }
+
+html_sidebars = {
+    '**': [
+        'navigation.html',
+        'relations.html',
+        'searchbox.html',
+        'versions.html',
+    ],
+}
+
+html_context = {
+    'display_lower_left': True,
+}