final corrections

Author: dkazanc

.github/workflows/httomo_docs.yml

@@ -8,12 +8,14 @@ on:
   push:
     branches:
       - main
+    tags:
+      - 'v*'
+  schedule:
+    - cron: '0 6 * * 1'
 
 jobs:
   build-docs-publish:
     runs-on: ubuntu-latest
-    env:
-      HTTOMO_BACKENDS_VERSION: "1.2.0"
     defaults:
       run:
         shell: bash -el {0}
@@ -35,8 +37,7 @@ jobs:
             init-shell: bash
 
         - name: Install httomo-backends
-          run: |
-            pip install --no-deps "httomo-backends==${HTTOMO_BACKENDS_VERSION}"
+          run: pip install --no-deps -r ./docs/source/doc-pip-requirements.txt
 
         - name: Generate full yaml pipelines using pipeline directives
           run: |
@@ -51,8 +52,16 @@ jobs:
         - name: Build docs
           run: sphinx-build -W --keep-going -a -E -b html ./docs/source/ ./docs/build/
 
+        - name: Check external links
+          if: github.event_name == 'schedule'
+          run: sphinx-build -W --keep-going -a -E -b linkcheck ./docs/source/ ./docs/linkcheck/
+
         - name: Publish docs
-          if: github.ref_type == 'tag' || github.ref_name == 'main'
+          if: >-
+            (github.event_name == 'push' &&
+            (github.ref_type == 'tag' || github.ref_name == 'main')) ||
+            (github.event_name == 'workflow_dispatch' &&
+            github.ref_name == 'main')
           run: ghp-import -n -p -f ./docs/build
           env:
             GITHUB_TOKEN: ${{ github.token }}

docs/build_sphinx_docs.bat

@@ -23,7 +23,8 @@ if exist "%SCRIPT_DIR%build" (
 rem -a writes all output files.
 rem -E rebuilds the Sphinx environment without using the saved cache.
 rem -b html selects the HTML builder.
-sphinx-build -a -E -b html "%SCRIPT_DIR%source" "%SCRIPT_DIR%build"
+rem -W treats warnings as errors; --keep-going reports all warnings in one run.
+sphinx-build -W --keep-going -a -E -b html "%SCRIPT_DIR%source" "%SCRIPT_DIR%build"
 set "EXIT_CODE=%ERRORLEVEL%"
 
 if not "%EXIT_CODE%"=="0" (

docs/source/_static/3d_setup.png

@@ -0,0 +1,32 @@
+/* Highlight selected pages in the primary (left) navigation only.
+ *
+ * The direct href selectors cover inactive links. When one of these pages is
+ * active, Sphinx replaces its href with "#". The :has() selectors identify
+ * the same navigation group through the other named link and select the
+ * active entry by its stable first/last position.
+ */
+.bd-sidebar-primary .bd-sidenav a[href$="yaml.html"],
+.bd-sidebar-primary .bd-sidenav:has(a[href$="versioned_downloads.html"])
+    > li:first-child
+    > a,
+.bd-sidebar-primary .bd-sidenav a[href$="versioned_downloads.html"],
+.bd-sidebar-primary .bd-sidenav:has(a[href$="yaml.html"])
+    > li:last-child
+    > a {
+    background-color: rgb(33 150 243 / 18%);
+    box-shadow: inset 4px 0 #2196f3;
+    border-radius: 0.25rem;
+    font-weight: 600;
+}
+
+/* The run_httomo link identifies the Getting started navigation group when
+ * Sphinx replaces the active quickstart link with href="#". */
+.bd-sidebar-primary .bd-sidenav a[href$="quickstart.html"],
+.bd-sidebar-primary .bd-sidenav:has(a[href$="run_httomo.html"])
+    > li:nth-child(2)
+    > a {
+    background-color: rgb(255 193 7 / 22%);
+    box-shadow: inset 4px 0 #d39e00;
+    border-radius: 0.25rem;
+    font-weight: 600;
+}