From 2a5636e4de7a7482dea1ec4998389bc3e25f64bf Mon Sep 17 00:00:00 2001 From: Sebastian Golebiewski Date: Tue, 21 Oct 2025 08:54:55 +0200 Subject: [PATCH 1/6] [DOCS] Introduce per-repo docs build workflow Co-authored-by: Jeremy Ouillette --- .github/actions/docs-build/action.yml | 189 ++++++++++++++++++++++++++ .github/workflows/docs-build.yml | 6 +- 2 files changed, 192 insertions(+), 3 deletions(-) create mode 100644 .github/actions/docs-build/action.yml diff --git a/.github/actions/docs-build/action.yml b/.github/actions/docs-build/action.yml new file mode 100644 index 000000000..3aee42455 --- /dev/null +++ b/.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 diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml index f3b4b47a6..aa4ff6f5b 100644 --- a/.github/workflows/docs-build.yml +++ b/.github/workflows/docs-build.yml @@ -41,7 +41,7 @@ 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 + uses: ./.github/actions/docs-build secrets: SYS_ORCH_GITHUB: ${{ secrets.SYS_ORCH_GITHUB }} DOC_AWS_ACCESS_KEY_ID: ${{ secrets.DOC_AWS_ACCESS_KEY_ID }} @@ -52,7 +52,7 @@ jobs: 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 + uses: ./.github/actions/docs-build secrets: SYS_ORCH_GITHUB: ${{ secrets.SYS_ORCH_GITHUB }} DOC_AWS_ACCESS_KEY_ID: ${{ secrets.DOC_AWS_ACCESS_KEY_ID }} @@ -64,7 +64,7 @@ jobs: 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 + uses: ./.github/actions/docs-build secrets: SYS_ORCH_GITHUB: ${{ secrets.SYS_ORCH_GITHUB }} DOC_AWS_ACCESS_KEY_ID: ${{ secrets.DOC_AWS_ACCESS_KEY_ID }} From 56fd90e21cc802c53592baa3f6ed1bb591c0e16e Mon Sep 17 00:00:00 2001 From: Sebastian Golebiewski Date: Wed, 22 Oct 2025 07:36:10 +0200 Subject: [PATCH 2/6] Reorganize headings --- docs/user-guide/getting-started-guide.md | 26 +++++++++++------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/user-guide/getting-started-guide.md b/docs/user-guide/getting-started-guide.md index 465f5ea52..eb3dc8b9e 100644 --- a/docs/user-guide/getting-started-guide.md +++ b/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 ``` -### Step 3: Build Intel® SceneScape container images +## Step 3: Build Intel® SceneScape container images Build container images: @@ -96,7 +94,7 @@ 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 @@ -104,7 +102,7 @@ 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,17 +115,17 @@ export SUPASS= make demo ``` -### Step 6: Verify a successful deployment +## Step 6: Verify a successful deployment If you are running remotely, connect using `"https://"` or `"https://"`, 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 <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: @@ -135,7 +133,7 @@ To stop the containers, use the following command in the project directory: 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: From 5ac2fa08edfb40430014344fac3c17017c09747b Mon Sep 17 00:00:00 2001 From: Sebastian Golebiewski Date: Mon, 27 Oct 2025 07:48:25 +0100 Subject: [PATCH 3/6] Applying suggestions --- .github/workflows/docs-build.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml index aa4ff6f5b..7357ee378 100644 --- a/.github/workflows/docs-build.yml +++ b/.github/workflows/docs-build.yml @@ -42,7 +42,7 @@ jobs: needs: filter if: ${{ needs.filter.outputs.toplevel_changed == 'true' }} uses: ./.github/actions/docs-build - secrets: + 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 }} @@ -53,7 +53,7 @@ jobs: needs: filter if: ${{ needs.filter.outputs.autocalibration_changed == 'true' }} uses: ./.github/actions/docs-build - secrets: + 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 }} @@ -65,7 +65,7 @@ jobs: needs: filter if: ${{ needs.filter.outputs.controller_changed == 'true' }} uses: ./.github/actions/docs-build - secrets: + 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 }} From db922d6954dc46357a3c80d13b2d3da740137c39 Mon Sep 17 00:00:00 2001 From: Sebastian Golebiewski Date: Tue, 28 Oct 2025 08:27:29 +0100 Subject: [PATCH 4/6] Additional fixes --- .github/workflows/docs-build.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml index 7357ee378..4d089a871 100644 --- a/.github/workflows/docs-build.yml +++ b/.github/workflows/docs-build.yml @@ -46,7 +46,6 @@ jobs: 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" @@ -57,7 +56,6 @@ jobs: 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: @@ -69,5 +67,4 @@ jobs: 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 From 6ec6d8779e4a23d31bfef4f8ae109bc5431f958b Mon Sep 17 00:00:00 2001 From: "Yermolenko, Dmytro" Date: Tue, 28 Oct 2025 19:58:35 +0100 Subject: [PATCH 5/6] Prettier Write --- .github/actions/docs-build/action.yml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/actions/docs-build/action.yml b/.github/actions/docs-build/action.yml index 3aee42455..f2a617e06 100644 --- a/.github/actions/docs-build/action.yml +++ b/.github/actions/docs-build/action.yml @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: (C) 2025 Intel Corporation # SPDX-License-Identifier: Apache-2.0 -name: 'Build Documentation' +name: "Build Documentation" inputs: docs_directory: @@ -23,7 +23,7 @@ inputs: Regex pattern to match against when selecting branches to build for version selector, defaults to '^(main|release-.*)$' required: false - default: '^(main|release-.*)$' + default: "^(main|release-.*)$" type: string simple_mode: description: >- @@ -76,7 +76,7 @@ runs: using: "composite" steps: - name: Checkout action repository - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 with: repository: open-edge-platform/orch-ci path: ci @@ -90,14 +90,14 @@ runs: bootstrap_tools: "aws" - name: Configure AWS credentials - uses: aws-actions/configure-aws-credentials@00943011d9042930efac3dcd3a170e4273319bc8 # v5.1.0 + 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 + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 with: # Fetch all history, otherwise sporadic issue with missing tags fetch-depth: 0 @@ -147,7 +147,7 @@ runs: done - name: Install Spark theme - if: false # Disable step - Spark theme deprecated + if: false # Disable step - Spark theme deprecated env: DOCS_DIR: ${{ inputs.docs_directory }} ENDPOINT: ${{ inputs.endpoint }} @@ -181,7 +181,7 @@ runs: # 'Post Bootstrap CI Environment' step does not fail - name: Checkout action repository if: always() - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 with: repository: open-edge-platform/orch-ci path: ci From 54e5e5684b2bc64f1ff0f53f30e638344afc9419 Mon Sep 17 00:00:00 2001 From: sgolebiewski-intel Date: Wed, 12 Nov 2025 09:42:32 +0100 Subject: [PATCH 6/6] Update the docs-build workflow --- .github/workflows/docs-build.yml | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml index 70968b219..c9ac1809b 100644 --- a/.github/workflows/docs-build.yml +++ b/.github/workflows/docs-build.yml @@ -15,6 +15,11 @@ on: # yamllint disable-line rule:truthy permissions: contents: read # needed for actions/checkout +env: + 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 }} + jobs: filter: name: "Filter Changed Documentation Paths" @@ -46,9 +51,9 @@ jobs: if: ${{ needs.filter.outputs.toplevel_changed == 'true' }} 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 }} + SYS_ORCH_GITHUB: ${{ env.SYS_ORCH_GITHUB }} + DOC_AWS_ACCESS_KEY_ID: ${{ env.DOC_AWS_ACCESS_KEY_ID }} + DOC_AWS_SECRET_ACCESS_KEY: ${{ env.DOC_AWS_SECRET_ACCESS_KEY }} exclude_patterns: "README.md, adr, design, development" build_autocalibration: @@ -57,9 +62,9 @@ jobs: if: ${{ needs.filter.outputs.autocalibration_changed == 'true' }} 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 }} + SYS_ORCH_GITHUB: ${{ env.SYS_ORCH_GITHUB }} + DOC_AWS_ACCESS_KEY_ID: ${{ env.DOC_AWS_ACCESS_KEY_ID }} + DOC_AWS_SECRET_ACCESS_KEY: ${{ env.DOC_AWS_SECRET_ACCESS_KEY }} docs_directory: autocalibration build_controller: @@ -68,19 +73,18 @@ jobs: if: ${{ needs.filter.outputs.controller_changed == 'true' }} 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 }} + SYS_ORCH_GITHUB: ${{ env.SYS_ORCH_GITHUB }} + DOC_AWS_ACCESS_KEY_ID: ${{ env.DOC_AWS_ACCESS_KEY_ID }} + DOC_AWS_SECRET_ACCESS_KEY: ${{ env.DOC_AWS_SECRET_ACCESS_KEY }} docs_directory: controller cluster_analytics: name: "Build Cluster Analytics Documentation" needs: filter if: ${{ needs.filter.outputs.cluster_analytics_changed == 'true' }} - uses: open-edge-platform/orch-ci/.github/workflows/build-documentation.yml@496b2d7495eb58fc290e90605d839bf27e51f3d0 - secrets: - 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 }} + uses: open-edge-platform/orch-ci/.github/workflows/build-documentation.yml@b14b0105bf312a2c98457dd021622de4c14f6bff with: + SYS_ORCH_GITHUB: ${{ env.SYS_ORCH_GITHUB }} + DOC_AWS_ACCESS_KEY_ID: ${{ env.DOC_AWS_ACCESS_KEY_ID }} + DOC_AWS_SECRET_ACCESS_KEY: ${{ env.DOC_AWS_SECRET_ACCESS_KEY }} docs_directory: cluster_analytics