Doc tweaks; adds logo

.github/workflows/docs.yml

@@ -3,6 +3,8 @@ name: Deploy docs to GitHub Pages
 on:
   push:
     branches: [main]
+  pull_request:
+    branches: [main]
 
 jobs:
   build:
@@ -11,9 +13,6 @@ jobs:
       contents: read
       pages: write
       id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -26,10 +25,22 @@ jobs:
         run: npm install -g jsdoc
       - name: Build docs
         run: sphinx-build -b html docs/ docs/_build
-      - name: Upload Pages artifact
+      - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs/_build
+          name: ${{ github.event_name == 'pull_request'
+            && format('github-pages-preview-{0}', github.event.number)
+            || 'github-pages' }}
+          path: docs/_build/
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.gitignore

@@ -1,3 +1,5 @@
+.DS_store
+
 # Compiled class file
 *.class
 

docs/_templates/sidebar-nav-global.html

@@ -0,0 +1,16 @@
+<nav class="bd-docs-nav bd-links"
+     aria-label="{{ _('Section Navigation') }}">
+  <p class="bd-links__title" role="heading" aria-level="1">{{ _("Section Navigation") }}</p>
+  <div class="bd-toc-item navbar-nav">
+    {{- generate_toctree_html(
+      "sidebar",
+      startdepth=0,
+      show_nav_level=theme_show_nav_level | int,
+      maxdepth=theme_navigation_depth | int,
+      collapse=theme_collapse_navigation | tobool,
+      includehidden=theme_sidebar_includehidden | tobool,
+      titles_only=True
+      )
+    -}}
+  </div>
+</nav>

docs/conf.py

@@ -23,6 +23,21 @@
 html_theme = 'pydata_sphinx_theme'
 html_static_path = ['_static']
 
+html_sidebars = {
+    "**": ["sidebar-collapse.html", "sidebar-nav-global.html"]
+}
+
+html_theme_options = {
+    "show_nav_level": 2,
+    "collapse_navigation": False,
+    "navigation_depth": 4,
+    "logo": {
+        "image_light": "_static/trx_logo.png",
+        "image_dark": "_static/trx_logo.png",
+        "alt_text": "trx-javascript",
+    },
+}
+
 myst_enable_extensions = [
     "colon_fence",
     "deflist",