diff --git a/.github/actions/docs-build/action.yml b/.github/actions/docs-build/action.yml new file mode 100644 index 000000000..f2a617e06 --- /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 90ff16623..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" @@ -44,46 +49,42 @@ 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@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: ./.github/actions/docs-build 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 }} 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@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: ./.github/actions/docs-build 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: 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@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: ./.github/actions/docs-build 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: 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 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: