[DOCS] Introduce per-repo docs build workflow

.github/actions/docs-build/action.yml

@@ -0,0 +1,189 @@
+---
+# SPDX-FileCopyrightText: (C) 2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+name: "Build Documentation"
+
+inputs:
+  docs_directory:
+    description: >-
+      Documentation directory where the job will run, defaults to '.'
+    required: false
+    default: "."
+    type: string
+  output_directory:
+    description: >-
+      Directory where the documentation HTML build is located,
+      defaults to 'out/html'
+    required: false
+    default: "out/html"
+    type: string
+  branch_pattern:
+    description: >-
+      Regex pattern to match against when selecting branches to build for
+      version selector, defaults to '^(main|release-.*)$'
+    required: false
+    default: "^(main|release-.*)$"
+    type: string
+  simple_mode:
+    description: >-
+      When true, override configuration for simple documentation sites
+    required: false
+    default: true
+    type: boolean
+  orch_ci_repo_ref:
+    description: >-
+      The ref of the orch-ci repo, including bootstrap action and scripts,
+      defaults to 'main'
+    required: false
+    default: "main"
+    type: string
+  endpoint:
+    description: >-
+      Endpoint URL where documentation will be deployed to,
+      defaults to 's3://intel-openedgeplatform-documentation'
+    required: false
+    default: "s3://intel-openedgeplatform-documentation"
+    type: string
+  distribution_id:
+    description: >-
+      Distribution ID of documentation hosting service,
+      defaults to 'E1QN7TZJG8M0VL'
+    required: false
+    default: "E1QN7TZJG8M0VL"
+    type: string
+  exclude_patterns:
+    description: >-
+      Comma separated list of exclude patterns to use during the build,
+      defaults to empty list
+    required: false
+    default: ""
+    type: string
+  SYS_ORCH_GITHUB:
+    description: "PAT (contents: read) to clone private repos"
+    required: true
+    type: string
+  DOC_AWS_ACCESS_KEY_ID:
+    description: AWS access key for docs bucket
+    required: true
+    type: string
+  DOC_AWS_SECRET_ACCESS_KEY:
+    description: AWS secret access key for docs bucket
+    required: true
+    type: string
+
+runs:
+  using: "composite"
+  steps:
+    - name: Checkout action repository
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      with:
+        repository: open-edge-platform/orch-ci
+        path: ci
+        ref: ${{ inputs.orch_ci_repo_ref }}
+        persist-credentials: false
+
+    - name: Bootstrap CI environment
+      uses: ./ci/.github/actions/bootstrap
+      with:
+        gh_token: ${{ inputs.SYS_ORCH_GITHUB }}
+        bootstrap_tools: "aws"
+
+    - name: Configure AWS credentials
+      uses: aws-actions/configure-aws-credentials@00943011d9042930efac3dcd3a170e4273319bc8 # v5.1.0
+      with:
+        aws-access-key-id: ${{ inputs.DOC_AWS_ACCESS_KEY_ID }}
+        aws-secret-access-key: ${{ inputs.DOC_AWS_SECRET_ACCESS_KEY }}
+        aws-region: us-west-2
+
+    - name: Checkout code
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      with:
+        # Fetch all history, otherwise sporadic issue with missing tags
+        fetch-depth: 0
+        # Fetch tags
+        fetch-tags: true
+        # Checkout the branch that triggered the workflow
+        # to avoid detached HEAD
+        ref: ${{ github.head_ref }}
+        persist-credentials: false
+
+    # Fetch template from AWS S3 bucket
+    - name: Checkout template
+      if: ${{ inputs.simple_mode }}
+      env:
+        ENDPOINT: ${{ inputs.endpoint }}
+      shell: bash
+      run: |
+        mkdir -p "${GITHUB_WORKSPACE}"/_template
+        aws s3 cp --recursive "${ENDPOINT}/template" \
+          "${GITHUB_WORKSPACE}"/_template
+
+    - name: Copy template
+      if: ${{ inputs.simple_mode }}
+      env:
+        DOCS_DIR: ${{ inputs.docs_directory }}
+      shell: bash
+      run: |
+        cd "${GITHUB_WORKSPACE}/${DOCS_DIR}"
+        # Override any existing files with template
+        cp -rf "${GITHUB_WORKSPACE}"/_template/* .
+        if [ -f "dictionary_append.txt" ]; then
+          cat "dictionary_append.txt" >> "dict.txt"
+        fi
+
+    - name: Add exclude patterns
+      env:
+        EXCLUDE: ${{ inputs.exclude_patterns }}
+      shell: bash
+      run: |
+        # Remove any spaces
+        exclude_no_spaces="${EXCLUDE// /}"
+        # Surround patterns with quotes and create Python list
+        exclude_pattern="[\"${exclude_no_spaces//,/\", \"}\"]"
+        conf_files=$(find "${GITHUB_WORKSPACE}" -type f -path "*/docs/conf.py")
+        for conf_file in $conf_files; do
+          echo "exclude_patterns.extend(${exclude_pattern})" >> "$conf_file"
+        done
+
+    - name: Install Spark theme
+      if: false # Disable step - Spark theme deprecated
+      env:
+        DOCS_DIR: ${{ inputs.docs_directory }}
+        ENDPOINT: ${{ inputs.endpoint }}
+      shell: bash
+      run: |
+        # Download Spark Sphinx theme
+        tmpdir="$(mktemp -d)"
+        aws s3 cp "${ENDPOINT}/theme/current" "${tmpdir}"
+        theme_wheel="$(cat "${tmpdir}/current")"
+        aws s3 cp "${ENDPOINT}/theme/${theme_wheel}" "${tmpdir}"
+        # Instantiate Python Virtual Environment
+        cd "${GITHUB_WORKSPACE}/${DOCS_DIR}"
+        make check
+        venv="$(find . -path '*/bin/activate' -name activate)"
+        # shellcheck source=/dev/null
+        source "${venv}"
+        # Install Spark Sphinx theme
+        pip3 install --no-input "${tmpdir}/${theme_wheel}"
+        deactivate
+
+    - name: Build Documentation
+      env:
+        DOCS_DIR: ${{ inputs.docs_directory }}
+        SIMPLE_MODE: ${{ inputs.simple_mode }}
+      shell: bash
+      run: |
+        cd "${GITHUB_WORKSPACE}/${DOCS_DIR}"
+        make build
+
+    # Checkout orch-ci again so the
+    # 'Post Bootstrap CI Environment' step does not fail
+    - name: Checkout action repository
+      if: always()
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      with:
+        repository: open-edge-platform/orch-ci
+        path: ci
+        ref: ${{ inputs.orch_ci_repo_ref }}
+        persist-credentials: false

.github/workflows/docs-build.yml

@@ -41,33 +41,30 @@ jobs:
     name: "Build Toplevel Documentation"
     needs: filter
     if: ${{ needs.filter.outputs.toplevel_changed == 'true' }}
-    uses: open-edge-platform/orch-ci/.github/workflows/build-documentation.yml@b14b0105bf312a2c98457dd021622de4c14f6bff
-    secrets:
+    uses: ./.github/actions/docs-build
+    with:
       SYS_ORCH_GITHUB: ${{ secrets.SYS_ORCH_GITHUB }}
       DOC_AWS_ACCESS_KEY_ID: ${{ secrets.DOC_AWS_ACCESS_KEY_ID }}
       DOC_AWS_SECRET_ACCESS_KEY: ${{ secrets.DOC_AWS_SECRET_ACCESS_KEY }}
-    with:
       exclude_patterns: "README.md, adr, design, development"
   build_autocalibration:
     name: "Build Autocalibration Documentation"
     needs: filter
     if: ${{ needs.filter.outputs.autocalibration_changed == 'true' }}
-    uses: open-edge-platform/orch-ci/.github/workflows/build-documentation.yml@b14b0105bf312a2c98457dd021622de4c14f6bff
-    secrets:
+    uses: ./.github/actions/docs-build
+    with:
       SYS_ORCH_GITHUB: ${{ secrets.SYS_ORCH_GITHUB }}
       DOC_AWS_ACCESS_KEY_ID: ${{ secrets.DOC_AWS_ACCESS_KEY_ID }}
       DOC_AWS_SECRET_ACCESS_KEY: ${{ secrets.DOC_AWS_SECRET_ACCESS_KEY }}
-    with:
       docs_directory: autocalibration
 
   build_controller:
     name: "Build Controller Documentation"
     needs: filter
     if: ${{ needs.filter.outputs.controller_changed == 'true' }}
-    uses: open-edge-platform/orch-ci/.github/workflows/build-documentation.yml@b14b0105bf312a2c98457dd021622de4c14f6bff
-    secrets:
+    uses: ./.github/actions/docs-build
+    with:
       SYS_ORCH_GITHUB: ${{ secrets.SYS_ORCH_GITHUB }}
       DOC_AWS_ACCESS_KEY_ID: ${{ secrets.DOC_AWS_ACCESS_KEY_ID }}
       DOC_AWS_SECRET_ACCESS_KEY: ${{ secrets.DOC_AWS_SECRET_ACCESS_KEY }}
-    with:
       docs_directory: controller

docs/user-guide/getting-started-guide.md

@@ -1,14 +1,12 @@
-# Getting Started with Intel® SceneScape
+# Get Started with Intel® SceneScape
 
 - **Time to Complete:** 30-45 minutes
 
-## Get Started
-
-### Prerequisites
+## Prerequisites
 
 Check [System Requirements](system-requirements.md) before proceeding with rest of the steps in this documentation.
 
-### Step 1: Install Prerequisites
+## Step 1: Install Prerequisites
 
 The prerequisite software can be installed via the following commands on the Ubuntu host OS:
 
@@ -43,7 +41,7 @@ docker --version
 docker run hello-world
 ```
 
-### Step 2: Download and extract code of a Intel® SceneScape release
+## Step 2: Download and extract code of a Intel® SceneScape release
 
 > **Note:** These operations must be executed when logged in as a standard (non-root) user. **Do NOT use root or sudo.**
 
@@ -57,7 +55,7 @@ docker run hello-world
 
 3. When downloading older Intel® SceneScape releases, follow instructions in `Getting-Started-Guide` specific to that version.
 
-#### Alternatively, get the Intel® SceneScape source code
+### Alternatively, get the Intel® SceneScape source code
 
 1. Clone the repository:
 
@@ -78,7 +76,7 @@ git tag
 git checkout <tag-version>
 ```
 
-### Step 3: Build Intel® SceneScape container images
+## Step 3: Build Intel® SceneScape container images
 
 Build container images:
 
@@ -96,15 +94,15 @@ Optionally, the number of jobs can be adjusted by setting the `JOBS` variable, e
 make JOBS=1
 ```
 
-### Step 4 (Optional): Build dependency list of Intel® SceneScape container images
+## Step 4 (Optional): Build dependency list of Intel® SceneScape container images
 
 ```bash
 make list-dependencies
 ```
 
 This step generates dependency lists. Two separate files are created for system packages and Python packages per each microservice image.
 
-### Step 5: Deploy Intel® SceneScape demo to the target system
+## Step 5: Deploy Intel® SceneScape demo to the target system
 
 Before deploying the demo of Intel® SceneScape for the first time, please set the environment variable SUPASS with the super user password for logging into Intel® SceneScape.
 Important: This should be different than the password for your system user.
@@ -117,25 +115,25 @@ export SUPASS=<password>
 make demo
 ```
 
-### Step 6: Verify a successful deployment
+## Step 6: Verify a successful deployment
 
 If you are running remotely, connect using `"https://<ip_address>"` or `"https://<hostname>"`, using the correct IP address or hostname of the remote Intel® SceneScape system. If accessing on a local system use `"https://localhost"`. If you see a certificate warning, click the prompts to continue to the site. For example, in Chrome click "Advanced" and then "Proceed to &lt;ip_address> (unsafe)".
 
 > **Note:** These certificate warnings are expected due to the use of a self-signed certificate for initial deployment purposes. This certificate is generated at deploy time and is unique to the instance.
 
-### Logging In
+## Log In
 
 Enter "admin" for the user name and the value you typed earlier for SUPASS.
 
-### Stopping the System
+## Stop the System
 
 To stop the containers, use the following command in the project directory:
 
 ```console
 docker compose down --remove-orphans
 ```
 
-### Starting the System
+## Start the System
 
 To start after the first time, use the following command in the project directory: