Merge pull request #1051 from thewtex/consolidated-doc-deployment

ci: configuration to build-deploy main docs to GitHub Pages
InsightSoftwareConsortium · Jan 29, 2024 · 1442d7a · 1442d7a
2 parents a9097b8 + 8e35701
commit 1442d7a
Show file tree

Hide file tree

Showing 31 changed files with 223 additions and 16 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,159 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-main-documentation:
+    runs-on: ubuntu-22.04
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.x'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r docs/requirements.txt
+
+    - name: Build documentation
+      run: |
+        cd docs/
+        make html
+
+    - name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: main-documentation
+        path: docs/_build/html
+
+  build-package-documentation:
+    runs-on: ubuntu-22.04
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Free Disk Space (Ubuntu)
+      uses: jlumbroso/free-disk-space@main
+
+    - name: Pull latest Docker images
+      run: |
+        ./src/docker/pull.sh
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+
+    - name: Install
+      uses: pnpm/action-setup@v2
+      with:
+        version: 8
+        run_install: true
+
+    - name: Build itk-wasm
+      run: |
+        pnpm build
+
+    - name: Build package typescript documentation
+      run: |
+        for package in compare-images compress-stringify dicom downsample image-io mesh-io; do
+          mkdir -p docs/$package/ts/docs
+          mkdir -p docs/$package/ts/app
+
+          sed "s%      basePath:.*%      basePath: '/$package/ts/docs',%" packages/$package/typescript/index.html > docs/$package/ts/docs/index.html
+          cp packages/$package/typescript/README.md docs/$package/ts/docs/
+          mkdir -p docs/$package/ts/docs/test/browser/demo-app
+          cp packages/$package/typescript/test/browser/demo-app/logo.svg docs/$package/ts/docs/test/browser/demo-app/
+
+          pushd packages/$package/typescript
+          rm -rf demo-app node_modules/.vite
+          export VITE_BASE_URL="/$package/ts/app/"
+          pnpm build
+          popd
+          rsync -a packages/$package/typescript/demo-app/ docs/$package/ts/app/
+        done
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Build package python documentation
+      run: |
+        for package in compare-images compress-stringify dicom downsample image-io mesh-io; do
+          mkdir -p docs/$package/py/docs
+          mkdir -p docs/$package/py/app
+
+          export SPHINX_BASE_URL="/$package/py/docs/"
+          pushd packages/$package/python/*$package/docs
+          pip install -r requirements.txt
+          make html
+          popd
+          rsync -a packages/$package/python/*$package/docs/_build/html/ docs/$package/py/docs/
+        done
+
+    - name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: package-documentation
+        path: docs
+
+  consolidate-documentation:
+    needs: [build-main-documentation, build-package-documentation]
+    runs-on: ubuntu-22.04
+
+    steps:
+    - name: Download main documentation
+      uses: actions/download-artifact@v4
+      with:
+        name: main-documentation
+        path: docs
+
+    - name: Download package documentation
+      uses: actions/download-artifact@v4
+      with:
+        name: package-documentation
+        path: docs
+
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docs
+
+  deploy-gh-pages:
+    needs: consolidate-documentation
+    runs-on: ubuntu-22.04
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      contents: read
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4
+      # with:
+        # preview: true <-> currently not available to the public
diff --git a/.github/workflows/javascript-typescript.yml b/.github/workflows/javascript-typescript.yml
@@ -15,7 +15,7 @@ jobs:
         package: [compress-stringify, compare-images, dicom, mesh-io, image-io, downsample]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: Free Disk Space (Ubuntu)
       uses: jlumbroso/free-disk-space@main

diff --git a/packages/compare-images/python/itkwasm-compare-images/docs/conf.py b/packages/compare-images/python/itkwasm-compare-images/docs/conf.py
@@ -7,6 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 from datetime import date
+import os
 
 project = 'itkwasm-compare-images'
 copyright = f'{date.today().year}, NumFOCUS'
@@ -46,6 +47,7 @@
 html_logo = "_static/logo.svg"
 html_favicon = "_static/favicon.png"
 html_title = f"{project}"
+html_baseurl = os.environ.get("SPHINX_BASE_URL", "")
 
 # Furo options
 html_theme_options = {

diff --git a/packages/compare-images/typescript/index.html b/packages/compare-images/typescript/index.html
@@ -24,7 +24,8 @@
   <div id="app">Loading...</div>
   <script>
     window.$docsify = {
-      logo: 'test/browser/demo-app/logo.svg',
+      basePath: '',
+      logo: '/test/browser/demo-app/logo.svg',
       name: '@itk-wasm/compare-images',
       repo: ''
     }

diff --git a/packages/compare-images/typescript/test/browser/demo-app/index.ts b/packages/compare-images/typescript/test/browser/demo-app/index.ts
@@ -1,7 +1,8 @@
 import * as compareImages from '../../../dist/index.js'
 
 // Use local, vendored WebAssembly module assets
-const pipelinesBaseUrl: string | URL = new URL('/pipelines', document.location.origin).href
+const viteBaseUrl = import.meta.env.BASE_URL
+const pipelinesBaseUrl: string | URL = new URL(`${viteBaseUrl}pipelines`, document.location.origin).href
 compareImages.setPipelinesBaseUrl(pipelinesBaseUrl)
 
 import './compare-images-controller.js'
diff --git a/packages/compare-images/typescript/vite.config.js b/packages/compare-images/typescript/vite.config.js
@@ -2,8 +2,11 @@ import { defineConfig } from 'vite'
 import { viteStaticCopy } from 'vite-plugin-static-copy'
 import path from 'path'
 
+const base = process.env.VITE_BASE_URL || '/'
+
 export default defineConfig({
   root: path.join('test', 'browser', 'demo-app'),
+  base,
   server: {
     port: 5175
   },

diff --git a/packages/compress-stringify/python/itkwasm-compress-stringify/docs/conf.py b/packages/compress-stringify/python/itkwasm-compress-stringify/docs/conf.py
@@ -7,6 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 from datetime import date
+import os
 
 project = 'itkwasm-compress-stringify'
 copyright = f'{date.today().year}, NumFOCUS'
@@ -45,6 +46,7 @@
 html_logo = "_static/logo.svg"
 html_favicon = "_static/favicon.png"
 html_title = f"{project}"
+html_baseurl = os.environ.get("SPHINX_BASE_URL", "")
 
 # Furo options
 html_theme_options = {

diff --git a/packages/compress-stringify/typescript/index.html b/packages/compress-stringify/typescript/index.html
@@ -24,7 +24,8 @@
   <div id="app">Loading...</div>
   <script>
     window.$docsify = {
-      logo: 'test/browser/demo-app/logo.svg',
+      basePath: '',
+      logo: '/test/browser/demo-app/logo.svg',
       name: '@itk-wasm/compress-stringify',
       repo: 'InsightSoftwareConsortium/itk-wasm'
     }

diff --git a/packages/compress-stringify/typescript/test/browser/demo-app/index.ts b/packages/compress-stringify/typescript/test/browser/demo-app/index.ts
@@ -4,7 +4,8 @@ import * as compressStringify from '../../../dist/index.js'
 globalThis.compressStringify = compressStringify
 
 // Use local, vendored WebAssembly module assets
-const pipelinesBaseUrl: string | URL = new URL('/pipelines', document.location.origin).href
+const viteBaseUrl = import.meta.env.BASE_URL
+const pipelinesBaseUrl: string | URL = new URL(`${viteBaseUrl}pipelines`, document.location.origin).href
 compressStringify.setPipelinesBaseUrl(pipelinesBaseUrl)
 
 

diff --git a/packages/compress-stringify/typescript/vite.config.js b/packages/compress-stringify/typescript/vite.config.js
@@ -2,8 +2,11 @@ import { defineConfig } from 'vite'
 import { viteStaticCopy } from 'vite-plugin-static-copy'
 import path from 'path'
 
+const base = process.env.VITE_BASE_URL || '/'
+
 export default defineConfig({
   root: path.join('test', 'browser', 'demo-app'),
+  base,
   server: {
     port: 5176
   },

diff --git a/packages/core/typescript/itk-wasm/src/bindgen/python/resources/docs/conf.py b/packages/core/typescript/itk-wasm/src/bindgen/python/resources/docs/conf.py
@@ -7,6 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 from datetime import date
+import os
 
 project = '@bindgenProject@'
 copyright = f'{date.today().year}, NumFOCUS'
@@ -46,6 +47,7 @@
 html_logo = "_static/logo.svg"
 html_favicon = "_static/favicon.png"
 html_title = f"{project}"
+html_baseurl = os.environ.get("SPHINX_BASE_URL", "")
 
 # Furo options
 html_theme_options = {

diff --git a/packages/core/typescript/itk-wasm/src/bindgen/typescript/resources/demo-app/index.ts b/packages/core/typescript/itk-wasm/src/bindgen/typescript/resources/demo-app/index.ts
@@ -2,7 +2,8 @@ import * as @bindgenBundleNameCamelCase@ from '../../../dist/index.js'
 globalThis.@bindgenBundleNameCamelCase@ = @bindgenBundleNameCamelCase@
 
 // Use local, vendored WebAssembly module assets
-const pipelinesBaseUrl: string | URL = new URL('/pipelines', document.location.origin).href
+const viteBaseUrl = import.meta.env.BASE_URL
+const pipelinesBaseUrl: string | URL = new URL(`${viteBaseUrl}pipelines`, document.location.origin).href
 @bindgenBundleNameCamelCase@.setPipelinesBaseUrl(pipelinesBaseUrl)
 
 @bindgenFunctionLogic@
diff --git a/packages/core/typescript/itk-wasm/src/bindgen/typescript/resources/index.html b/packages/core/typescript/itk-wasm/src/bindgen/typescript/resources/index.html
@@ -24,7 +24,8 @@
   <div id="app">Loading...</div>
   <script>
     window.$docsify = {
-      logo: 'test/browser/demo-app/logo.svg',
+      basePath: '',
+      logo: '/test/browser/demo-app/logo.svg',
       name: '<bindgenPackageName>',
       repo: ''
     }

diff --git a/packages/core/typescript/itk-wasm/src/bindgen/typescript/resources/vite.config.js b/packages/core/typescript/itk-wasm/src/bindgen/typescript/resources/vite.config.js
@@ -2,8 +2,11 @@ import { defineConfig } from 'vite'
 import { viteStaticCopy } from 'vite-plugin-static-copy'
 import path from 'path'
 
+const base = process.env.VITE_BASE_URL || '/'
+
 export default defineConfig({
   root: path.join('test', 'browser', 'demo-app'),
+  base,
   build: {
     outDir: '../../../demo-app',
     emptyOutDir: true,

diff --git a/...bindgen-interface-types-pipeline/python/itkwasm-bindgen-interface-types-test/docs/conf.py b/...bindgen-interface-types-pipeline/python/itkwasm-bindgen-interface-types-test/docs/conf.py
@@ -7,6 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 from datetime import date
+import os
 
 project = 'itkwasm-bindgen-interface-types-test'
 copyright = f'{date.today().year}, NumFOCUS'
@@ -46,6 +47,7 @@
 html_logo = "_static/logo.svg"
 html_favicon = "_static/favicon.png"
 html_title = f"{project}"
+html_baseurl = os.environ.get("SPHINX_BASE_URL", "")
 
 # Furo options
 html_theme_options = {

diff --git a/packages/dicom/python/itkwasm-dicom/docs/conf.py b/packages/dicom/python/itkwasm-dicom/docs/conf.py
@@ -7,6 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 from datetime import date
+import os
 
 project = 'itkwasm-dicom'
 copyright = f'{date.today().year}, NumFOCUS'
@@ -46,6 +47,7 @@
 html_logo = "_static/logo.svg"
 html_favicon = "_static/favicon.png"
 html_title = f"{project}"
+html_baseurl = os.environ.get("SPHINX_BASE_URL", "")
 
 # Furo options
 html_theme_options = {

diff --git a/packages/dicom/typescript/index.html b/packages/dicom/typescript/index.html
@@ -24,7 +24,8 @@
   <div id="app">Loading...</div>
   <script>
     window.$docsify = {
-      logo: 'test/browser/demo-app/logo.svg',
+      basePath: '',
+      logo: '/test/browser/demo-app/logo.svg',
       name: '@itk-wasm/dicom',
       repo: 'InsightSoftwareConsortium/itk-wasm'
     }

diff --git a/packages/dicom/typescript/test/browser/demo-app/index.ts b/packages/dicom/typescript/test/browser/demo-app/index.ts
@@ -4,7 +4,8 @@ import * as dicom from '../../../dist/index.js'
 globalThis.dicom = dicom
 
 // Use local, vendored WebAssembly module assets
-const pipelinesBaseUrl: string | URL = new URL('/pipelines', document.location.origin).href
+const viteBaseUrl = import.meta.env.BASE_URL
+const pipelinesBaseUrl: string | URL = new URL(`${viteBaseUrl}pipelines`, document.location.origin).href
 dicom.setPipelinesBaseUrl(pipelinesBaseUrl)
 
 

diff --git a/packages/dicom/typescript/vite.config.js b/packages/dicom/typescript/vite.config.js
@@ -2,8 +2,11 @@ import { defineConfig } from 'vite'
 import { viteStaticCopy } from 'vite-plugin-static-copy'
 import path from 'path'
 
+const base = process.env.VITE_BASE_URL || '/'
+
 export default defineConfig({
   root: path.join('test', 'browser', 'demo-app'),
+  base,
   server: {
     port: 5177
   },

diff --git a/packages/downsample/python/itkwasm-downsample/docs/conf.py b/packages/downsample/python/itkwasm-downsample/docs/conf.py
@@ -7,6 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 from datetime import date
+import os
 
 project = 'itkwasm-downsample'
 copyright = f'{date.today().year}, NumFOCUS'
@@ -46,6 +47,7 @@
 html_logo = "_static/logo.svg"
 html_favicon = "_static/favicon.png"
 html_title = f"{project}"
+html_baseurl = os.environ.get("SPHINX_BASE_URL", "")
 
 # Furo options
 html_theme_options = {