doc: build docs on readthedocs

docs/.readthedocs.yaml

@@ -0,0 +1,20 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3"
+
+  jobs:
+    post_create_environment:
+      # Install poetry
+      - asdf plugin add poetry
+      - asdf install poetry latest
+      - asdf global poetry latest
+      - poetry config virtualenvs.create false
+    post_install:
+      # Install deps and build using poetry
+      - . "$READTHEDOCS_VIRTUALENV_PATH/bin/activate" && cd docs && poetry install
+
+mkdocs:
+  configuration: docs/mkdocs.yml

docs/docs/scripts/readthedocs.js

@@ -0,0 +1,24 @@
+// Use CustomEvent to generate the version selector
+document.addEventListener(
+    "readthedocs-addons-data-ready",
+    function (event) {
+    const config = event.detail.data();
+    const versioning = `
+<div class="md-version">
+<button class="md-version__current" aria-label="Select version">
+${config.versions.current.slug}
+</button>
+
+<ul class="md-version__list">
+${ config.versions.active.map(
+(version) => `
+<li class="md-version__item">
+<a href="${ version.urls.documentation }" class="md-version__link">
+    ${ version.slug }
+</a>
+        </li>`).join("\n")}
+</ul>
+</div>`;
+
+document.querySelector(".md-header__topic").insertAdjacentHTML("beforeend", versioning);
+});

docs/docs/stylesheets/global.css

@@ -16,4 +16,17 @@ TODO: find a way to show all pages in left sidebar
 /* Remove cookie consent overlay */
 .md-consent__overlay {
   display:none;
+}
+
+/* Adjust readthedocs flyout menu */
+:root {
+  /* Reduce Read the Docs' flyout font a little bit */
+  --readthedocs-flyout-font-size: 0.7rem;
+
+  /* Reduce Read the Docs' notification font a little bit */
+  --readthedocs-notification-font-size: 0.8rem;
+
+  /* This customization is not yet perfect because we can't change the `line-height` yet. */
+  /* See https://github.com/readthedocs/addons/issues/197 */
+  --readthedocs-search-font-size: 0.7rem;
 }

docs/macros.py

@@ -42,7 +42,8 @@ def symlink_external_dirs():
 
         except Exception as e:
             logging.error(f"Error creating symlinks: {e}")
-            raise e
+            # Don't raise an error here for now
+            # raise e
 
     # Execute the symlink creation
     symlink_external_dirs()

docs/mkdocs.yml

@@ -14,6 +14,9 @@ extra_css:
   - stylesheets/global.css
   - stylesheets/notebooks.css
 
+extra_javascript:
+  - scripts/readthedocs.js
+
 theme:
   name: material
   custom_dir: overrides
@@ -115,6 +118,7 @@ plugins:
         #- icechunk-python
         - assets
         - stylesheets
+        - scripts
         - index.md
       generate_home_index: false
   - mermaid2

docs/overrides/main.html

@@ -1 +1,6 @@
-{% extends "base.html" %}
+{% extends "base.html" %}
+
+{% block site_meta %}
+{{ super() }}
+<meta name="readthedocs-addons-api-version" content="1" />
+{% endblock %}