prepare self-hosting of docs (#95)

* prepare self-hosting of docs

* update workflow

* update workflow

* update workflow

* update workflow

* update workflow

* change workflow

* dynamically adjust branch whitelist for PRs

* use abs path for the sphinx gallery examples dir

* update workflow

---------

Co-authored-by: Georg Schramm <[email protected]>

.github/workflows/gh_pages_doc.yml

@@ -0,0 +1,41 @@
+name: Build and Deploy docs to GH pages
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - "v*"
+  pull_request:
+    branches: ["master"]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -el {0}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0 # Fetch all history for all branches and tags
+
+      - name: Set up Miniconda
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          miniforge-version: latest
+          python-version: 3.12 # Specify the Python version compatible with your environment
+          environment-file: docs/environment.yml # Use your environment.yml to install dependencies
+          activate-environment: readthedocs # Name from environment.yml
+          auto-activate-base: false
+      - run: |
+          sphinx-multiversion docs/source _build/html
+
+      # Conditional deployment step
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' # Only run on push to main branch, not on PRs
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/html

.gitignore

@@ -2,6 +2,7 @@
 __pycache__/
 *.py[cod]
 *$py.class
+_build/
 
 # C extensions
 *.so

docs/environment.yml

@@ -9,7 +9,9 @@ dependencies:
   - sphinx-design
   - sphinx-copybutton
   - sphinxcontrib-bibtex
+  - sphinx-multiversion
   - libparallelproj
+  - matplotlib
+  - array-api-compat
   - pytorch
   - scipy
-

docs/source/_templates/versions.html

@@ -0,0 +1,27 @@
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    v: {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {%- if versions.tags %}
+    <dl>
+      <dt>Tags</dt>
+      {%- for item in versions.tags %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+    {%- if versions.branches %}
+    <dl>
+      <dt>Branches</dt>
+      {%- for item in versions.branches %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+  </div>
+</div>
+{%- endif %}

docs/source/conf.py

@@ -16,6 +16,9 @@
 with open("../../pyproject.toml", "rb") as f:
     project_data = tomllib.load(f)["project"]
 
+# Set the base directory
+docs_dir = os.path.abspath(os.path.dirname(__file__))
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -39,9 +42,10 @@
     "sphinx_design",
     "sphinx_copybutton",
     "sphinxcontrib.bibtex",
+    "sphinx_multiversion",
 ]
 
-bibtex_bibfiles = ["refs.bib"]
+bibtex_bibfiles = [os.path.abspath(os.path.join(os.path.dirname(__file__), "refs.bib"))]
 templates_path = ["_templates"]
 exclude_patterns = []
 
@@ -54,7 +58,9 @@
 
 
 sphinx_gallery_conf = {
-    "examples_dirs": ["../../examples"],
+    "examples_dirs": [
+        os.path.abspath(os.path.join(os.path.dirname(__file__), "../../examples"))
+    ],
     "filename_pattern": r"/\d{2}_run_",
     "example_extensions": {".py"},
     "run_stale_examples": True,
@@ -75,20 +81,23 @@
     "line_numbers": True,
     "recommender": {"enable": True, "n_examples": 4},
     "matplotlib_animations": True,
-    "default_thumb_file": "./parallelproj-thumbnail.png",
+    "default_thumb_file": os.path.join(
+        docs_dir, "_static", "parallelproj-thumbnail.png"
+    ),
 }
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
+html_static_path = ["_static"]
 html_theme = "sphinx_rtd_theme"
-html_logo = "parallelproj-logo.svg"
+html_logo = os.path.join(docs_dir, "_static", "parallelproj-logo.svg")
 
 html_theme_options = {
     "analytics_id": "G-WFK38K0TGS",
     "analytics_anonymize_ip": True,
     "logo_only": True,
-    "display_version": True,
+    # "display_version": True,
     "prev_next_buttons_location": "bottom",
     "style_external_links": False,
     "vcs_pageview_mode": "",
@@ -101,13 +110,30 @@
     "titles_only": False,
 }
 
+html_sidebars = {
+    "**": [
+        "versioning.html",
+    ],
+}
+
 # html_context = {
 #  'display_github': True,
 #  'github_user': 'gschramm',
 #  'github_repo': 'parallelproj',
 #  'github_version': 'master/docs/source/',
 # }
 
+# sphinx multiversion settings
+smv_tag_whitelist = (
+    r"^v(1\.(1[0-9]|[2-9][0-9])\.\d+|[2-9]\d*\.\d+\.\d+)$"  # build versions >= v1.10.0
+)
+smv_latest_version = "master"
+
+smv_branch_whitelist = r"^master|stable$"  # Include specific branches
+# Allow all branches when building in a PR context
+if os.environ.get("GITHUB_EVENT_NAME") == "pull_request":
+    smv_branch_whitelist = r".*"
+
 # -- Options for EPUB output -------------------------------------------------
 epub_show_urls = "footnote"