Adopt Furo documentation

Author: galjos

.github/workflows/pages.yml

@@ -9,12 +9,8 @@ on:
 permissions:
   contents: read
 
-concurrency:
-  group: pages
-  cancel-in-progress: true
-
 jobs:
-  deploy:
+  build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
@@ -33,9 +29,9 @@ jobs:
         run: python -m pip install '.[docs,ase]'
       - name: Build documentation
         run: >-
-          python -m sphinx -W -b html
+          python -m sphinx -W --keep-going -b html
           -d _build/doctrees
-          docs _site/PQViewer
+          docs _site
       - name: Install frontend dependencies
         working-directory: frontend
         run: npm ci
@@ -44,38 +40,33 @@ jobs:
         env:
           VITE_STATIC_DEMO: "true"
           VITE_BASE_PATH: /PQViewer/viewer/
-          PQVIEWER_OUT_DIR: ../_site/PQViewer/viewer
+          PQVIEWER_OUT_DIR: ../_site/viewer
         run: npm run build
       - name: Pack the perovskite demo
         run: >-
           python scripts/build_static_demo.py
           examples/strontium-titanate.extxyz
-          _site/PQViewer/viewer/demo
-      - name: Configure deployment key
-        env:
-          DOCS_DEPLOY_KEY: ${{ secrets.DOCS_DEPLOY_KEY }}
-        run: |
-          if [ -z "$DOCS_DEPLOY_KEY" ]; then
-            echo "::error::DOCS_DEPLOY_KEY is not configured"
-            exit 1
-          fi
-          install -m 700 -d ~/.ssh
-          printf '%s\n' "$DOCS_DEPLOY_KEY" > ~/.ssh/id_ed25519
-          chmod 600 ~/.ssh/id_ed25519
-          printf '%s\n' \
-            "github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl" \
-            > ~/.ssh/known_hosts
-      - name: Publish generated site
-        run: |
-          git clone --branch gh-pages --single-branch \
-            git@github.com:MolarVerse/molarverse.github.io.git _pages
-          rsync -a --delete _site/PQViewer/ _pages/PQViewer/
-          touch _pages/.nojekyll
-          git -C _pages config user.name "github-actions[bot]"
-          git -C _pages config user.email \
-            "41898282+github-actions[bot]@users.noreply.github.com"
-          git -C _pages add -- .nojekyll PQViewer
-          if ! git -C _pages diff --cached --quiet; then
-            git -C _pages commit -m "Update PQViewer documentation"
-            git -C _pages push origin gh-pages
-          fi
+          _site/viewer/demo
+      - name: Prepare Pages
+        run: touch _site/.nojekyll
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

docs/_static/custom.css

@@ -1,41 +1,27 @@
-:root {
-  --pst-color-primary: #1f718f;
-  --pst-color-secondary: #12313a;
-  --pst-color-link: #176c8c;
-  --pst-color-link-hover: #0d4e66;
-  --pst-font-family-base-system: Inter, ui-sans-serif, -apple-system,
-    BlinkMacSystemFont, "Segoe UI", sans-serif;
-  --pst-font-family-monospace-system: "SFMono-Regular", Consolas,
-    "Liberation Mono", monospace;
-}
+/* PQViewer-specific additions to Furo. */
 
-html[data-theme="dark"] {
-  --pst-color-primary: #65bddb;
-  --pst-color-secondary: #94ccd9;
-  --pst-color-link: #65bddb;
-  --pst-color-link-hover: #9ed9eb;
-  --pst-color-background: #0d171b;
-  --pst-color-on-background: #e7eff0;
-  --pst-color-surface: #142228;
+.sd-card {
+  box-shadow: none;
+  transition: transform 0.15s ease, box-shadow 0.15s ease;
 }
 
-.bd-page-width {
-  max-width: 88rem;
+.sd-card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.08);
 }
 
-.navbar-brand img {
-  width: 2rem;
-  height: 2rem;
+.content p code.literal,
+.content li code.literal {
+  background: var(--color-code-background);
+  border-radius: 0.2em;
 }
 
-.navbar-brand.logo .title {
-  font-weight: 700;
-  letter-spacing: -0.02em;
+.sidebar-logo {
+  width: 4rem;
 }
 
-.bd-article h1,
-.bd-article h2,
-.bd-article h3 {
+.sidebar-brand-text {
+  font-weight: 700;
   letter-spacing: -0.02em;
 }
 
@@ -45,16 +31,16 @@ html[data-theme="dark"] {
 
 .pq-workspace img {
   width: 100%;
-  border: 1px solid var(--pst-color-border);
+  border: 1px solid var(--color-foreground-border);
   border-radius: 0.35rem;
 }
 
 .pq-demo-shell {
   margin: 1.5rem 0 2rem;
   overflow: hidden;
-  border: 1px solid var(--pst-color-border);
+  border: 1px solid var(--color-background-border);
   border-radius: 0.55rem;
-  background: var(--pst-color-surface);
+  background: var(--color-background-secondary);
 }
 
 .pq-demo-heading {
@@ -63,7 +49,7 @@ html[data-theme="dark"] {
   align-items: center;
   justify-content: space-between;
   padding: 0.75rem 0.9rem;
-  border-bottom: 1px solid var(--pst-color-border);
+  border-bottom: 1px solid var(--color-background-border);
 }
 
 .pq-demo-heading div {
@@ -72,7 +58,7 @@ html[data-theme="dark"] {
 }
 
 .pq-demo-heading span {
-  color: var(--pst-color-text-muted);
+  color: var(--color-foreground-secondary);
   font-size: 0.86rem;
 }
 
@@ -90,27 +76,13 @@ html[data-theme="dark"] {
   background: #f6f8f8;
 }
 
-.sd-card {
-  box-shadow: none;
-}
-
 .sd-card-img-top {
   aspect-ratio: 4 / 3;
-  border-bottom: 1px solid var(--pst-color-border);
-  background: var(--pst-color-surface);
+  border-bottom: 1px solid var(--color-background-border);
+  background: var(--color-background-secondary);
   object-fit: cover;
 }
 
-.sd-card:hover {
-  border-color: var(--pst-color-primary);
-}
-
-@media screen and (max-width: 67.99em) {
-  .bd-main .bd-content .bd-article-container {
-    max-width: 100%;
-  }
-}
-
 @media screen and (max-width: 40em) {
   .pq-demo-heading {
     align-items: flex-start;

docs/conf.py

@@ -4,15 +4,21 @@
 
 extensions = [
     "myst_parser",
+    "sphinx_copybutton",
     "sphinx_design",
 ]
 
+copybutton_prompt_text = r">>> |\.\.\. |\$ "
+copybutton_prompt_is_regexp = True
+
 source_suffix = {
     ".md": "markdown",
 }
 root_doc = "index"
 exclude_patterns = [
     "_build",
+    "Thumbs.db",
+    ".DS_Store",
 ]
 
 myst_enable_extensions = [
@@ -22,30 +28,46 @@
 ]
 myst_heading_anchors = 3
 
-html_theme = "pydata_sphinx_theme"
-html_title = "PQViewer documentation"
+html_theme = "furo"
+html_title = "PQViewer"
 html_logo = "assets/brand/pq-logo.png"
 html_favicon = "assets/brand/pq-logo.png"
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
-html_context = {
-    "default_mode": "auto",
-}
 
 html_theme_options = {
-    "logo": {
-        "text": "PQViewer",
+    "sidebar_hide_name": False,
+    "light_css_variables": {
+        "color-brand-primary": "#1f718f",
+        "color-brand-content": "#176c8c",
     },
-    "github_url": "https://github.com/MolarVerse/PQViewer",
-    "navbar_align": "left",
-    "navigation_with_keys": True,
-    "show_nav_level": 1,
-    "show_toc_level": 2,
-    "secondary_sidebar_items": ["page-toc"],
-    "footer_start": ["copyright"],
-    "footer_end": ["sphinx-version"],
+    "dark_css_variables": {
+        "color-brand-primary": "#65bddb",
+        "color-brand-content": "#65bddb",
+    },
+    "source_repository": "https://github.com/MolarVerse/PQViewer/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/MolarVerse/PQViewer",
+            "html": (
+                '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
+                'viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8 0C3.58 0 0 '
+                '3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01'
+                '-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13'
+                '-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 '
+                '2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31'
+                '-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 '
+                '1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 '
+                '1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 '
+                '3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55'
+                '.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg>'
+            ),
+            "class": "",
+        },
+    ],
 }
 
-html_sidebars = {
-    "**": ["sidebar-nav-bs.html"],
-}
+html_baseurl = "https://molarverse.github.io/PQViewer/"

docs/index.md

@@ -204,6 +204,7 @@ examples.
 ```{toctree}
 :hidden:
 :maxdepth: 2
+:caption: Contents
 
 getting-started
 web-demo

docs/web-demo.md

@@ -33,5 +33,6 @@ features. The local server binds to `127.0.0.1` by default.
 
 ## Deployment
 
-The Pages workflow builds this documentation and the fixed-dataset viewer, then
-publishes the generated files under `/PQViewer/` on the MolarVerse Pages site.
+The Pages workflow builds this documentation and the fixed-dataset viewer as
+one artifact. Pushes to `main` publish it through the repository's GitHub Pages
+environment.

pyproject.toml

@@ -34,9 +34,10 @@ jupyter = [
     "ipython>=8,<10",
 ]
 docs = [
+    "furo>=2024.8.6,<2027",
     "myst-parser>=4,<5",
-    "pydata-sphinx-theme>=0.16,<1",
     "sphinx>=8,<9",
+    "sphinx-copybutton>=0.5,<1",
     "sphinx-design>=0.6,<1",
 ]
 dev = [