Move PX4 Guide source into /docs (#24490)

* Add vitepress tree

* Update existing workflows so they dont trigger on changes in the docs path

* Add nojekyll, package.json, LICENCE etc

* Add crowdin docs upload/download scripts

* Add docs flaw checker workflows

* Used docs prefix for docs workflows

* Crowdin obvious fixes

* ci: docs move to self hosted runner

runs on a beefy server for faster builds

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: don't run build action for docs or ci changes

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: update runners

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* Add docs/en

* Add docs assets and scripts

* Fix up editlinks to point to PX4 sources

* Download just the translations that are supported

* Add translation sources for zh, uk, ko

* Update latest tranlsation and uorb graphs

* update vitepress to latest

---------

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Ramon Roche <mrpollo@gmail.com>

.github/workflows/build_all_targets.yml

@@ -14,9 +14,15 @@ on:
       - 'stable'
       - 'beta'
       - 'release/**'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
       - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   group_targets:

.github/workflows/checks.yml

@@ -4,9 +4,15 @@ on:
   push:
     branches:
     - 'main'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
     - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   build:

.github/workflows/clang-tidy.yml

@@ -4,10 +4,15 @@ on:
   push:
     branches:
     - 'main'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
     - '*'
-
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 jobs:
   build:
     runs-on: ubuntu-latest

.github/workflows/compile_macos.yml

@@ -4,9 +4,15 @@ on:
   push:
     branches:
     - 'main'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
     - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   build:

.github/workflows/compile_ubuntu.yml

@@ -7,9 +7,15 @@ on:
       - 'stable'
       - 'beta'
       - 'release/**'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
       - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   build_and_test:

.github/workflows/dev_container.yml

@@ -10,9 +10,15 @@ on:
       - 'release/**'
     tags:
       - 'v*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
       - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   build:

.github/workflows/docs_crowdin_download.yml

@@ -0,0 +1,50 @@
+name: Docs - Crowdin - Download Guide Translations
+
+# https://github.com/crowdin/github-action/tree/master
+
+on:
+  schedule:
+    - cron: '0 0 * * 0' # Runs every Sunday at 00:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  synchronize-with-crowdin:
+    name: Synchronize with Crowdin
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      max-parallel: 1 # Should be 1 to avoid parallel builds
+      matrix:
+        lc: [ko, uk, zh] # Target languages https://developer.crowdin.com/language-codes/
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Matrix
+        uses: crowdin/github-action@v2
+        with:
+          config: 'docs/crowdin.yml'
+          upload_sources: false
+          upload_translations: false
+          download_translations: true
+          commit_message: New Crowdin translations - ${{ matrix.lc }}
+          localization_branch_name: l10n_crowdin_docs_translations_${{ matrix.lc }}
+          crowdin_branch_name: main
+          create_pull_request: true
+          pull_request_base_branch_name: 'main'
+          pull_request_title: New PX4 guide translations (Crowdin) - ${{ matrix.lc }}
+          pull_request_body: 'New PX4 guide Crowdin translations by [Crowdin GH Action](https://github.com/crowdin/github-action) for ${{ matrix.lc }}'
+          download_language: ${{ matrix.lc }}
+        env:
+          # A classic GitHub Personal Access Token with the 'repo' scope selected (the user should have write access to the repository).
+          GITHUB_TOKEN: ${{ secrets.PX4BUILDBOT_ACCESSTOKEN }}
+
+          # A numeric ID, found at https://crowdin.com/project/<projectName>/tools/api
+          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_DOCS_PROJECT_ID }}
+
+          # Visit https://crowdin.com/settings#api-key to create this token
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.PX4BUILDBOT_CROWDIN_PERSONAL_TOKEN }}

.github/workflows/docs_crowdin_upload.yml

@@ -0,0 +1,44 @@
+name: Docs - Crowdin - Upload Guide sources (en)
+
+# https://github.com/crowdin/github-action/tree/master
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/en/**'
+  pull_request:
+    types:
+      - closed
+    branches:
+      - main
+    paths:
+      - 'docs/en/**'
+  workflow_dispatch:
+
+jobs:
+  upload-to-crowdin:
+    if: github.event.pull_request.merged == true || github.event_name == 'push'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: crowdin push
+        uses: crowdin/github-action@v2
+        with:
+          config: 'docs/crowdin.yml'
+          upload_sources: true
+          upload_translations: false
+          download_translations: false
+          crowdin_branch_name: main
+        env:
+          # A classic GitHub Personal Access Token with the 'repo' scope selected (the user should have write access to the repository).
+          GITHUB_TOKEN: ${{ secrets.PX4BUILDBOT_ACCESSTOKEN }}
+
+          # A numeric ID, found at https://crowdin.com/project/<projectName>/tools/api
+          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_DOCS_PROJECT_ID }}
+
+          # Visit https://crowdin.com/settings#api-key to create this token
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.PX4BUILDBOT_CROWDIN_PERSONAL_TOKEN }}

.github/workflows/docs_deploy.yml

@@ -0,0 +1,96 @@
+name: Docs - Deploy PX4 User Guide
+
+on:
+  push:
+    branches:
+      - 'main'
+      - 'release/**'
+    tags:
+      - 'v*'
+    paths:
+      - 'docs/en/**'
+  pull_request:
+    branches:
+      - '*'
+    paths:
+      - 'docs/en/**'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# 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
+
+env:
+  BRANCH_NAME: ${{ github.head_ref || github.ref_name }}
+
+jobs:
+  build:
+    runs-on: [runs-on,runner=8cpu-linux-x64,image=ubuntu24-full-x64,"run-id=${{ github.run_id }}",spot=false,extras=s3-cache]
+    steps:
+      - uses: runs-on/action@v1
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          # Specify the path to lock file for correct caching
+          cache-dependency-path: ./docs/yarn.lock
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile --cwd ./docs
+
+      - name: Build with VitePress
+        working-directory: ./docs
+        run: |
+          npm run docs:build_ubuntu
+          touch .vitepress/dist/.nojekyll
+          npm run docs:sitemap
+
+      - name: Upload artifact
+        if: ${{ github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.merged) || github.event_name == 'workflow_dispatch' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: px4_docs_build
+          path: docs/.vitepress/dist/
+          retention-days: 1
+
+  deploy:
+    if: ${{ github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.merged) || github.event_name == 'workflow_dispatch' }}
+    needs: build
+    runs-on: [runs-on,runner=2cpu-linux-x64,image=ubuntu24-full-x64,"run-id=${{ github.run_id }}",spot=false]
+
+    steps:
+      - name: Download Artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: px4_docs_build
+          path: ~/_book
+
+      - name: Deploy
+        run: |
+          git clone --single-branch --branch main https://${{ secrets.PX4BUILTBOT_PERSONAL_ACCESS_TOKEN }}@github.com/PX4/docs.px4.io.git
+          rm -rf docs.px4.io/${BRANCH_NAME}
+          mkdir -p docs.px4.io/${BRANCH_NAME}
+          cp -r ~/_book/* docs.px4.io/${BRANCH_NAME}/
+          cd docs.px4.io
+          git config --global user.name "${{ secrets.PX4BUILDBOT_USER }}"
+          git config --global user.email "${{ secrets.PX4BUILDBOT_EMAIL }}"
+          git add ${BRANCH_NAME}
+          git commit -a -m "PX4 docs build update (vitepress) `date`"
+          #git add .
+          #git commit --amend -m "PX4 docs build update (vitepress) `date`"
+          #git commit --allow-empty -m "Empty commit to force rebuild"
+          git push origin main -f

.github/workflows/docs_flaw_checker.yml

@@ -0,0 +1,74 @@
+name: Docs - Check for flaws in PX4 Guide Source
+# So far:
+  # Modifications of translations files
+  # Broken internal links
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize]
+    paths:
+      - 'docs/en/**'
+
+jobs:
+  check_flaws:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Install Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+
+      - name: Create logs directory
+        run: |
+          mkdir logs
+
+      - name: Get changed english files
+        id: get_changed_markdown_english
+        uses: tj-actions/changed-files@v35.9.2
+        with:
+          json: true
+          base_sha: "${{ github.event.pull_request.base.sha }}"
+          sha: "${{ github.event.pull_request.head.sha }}"
+          # Below are used to output files to a directory. May use in flaw checker.
+          # write_output_files: true
+          # output_dir: "./logs"
+          files: |
+            docs/en/**/*.md
+
+      - name: Save JSON file containing files to link check
+        run: |
+          echo "${{ steps.get_changed_markdown_english.outputs.all_changed_files }}"
+          echo "${{ steps.get_changed_markdown_english.outputs.all_changed_files }}" > ./logs/prFiles.json
+
+      - name: Run link checker
+        id: link-check
+        run: |
+          npm -g install markdown_link_checker_sc@0.0.134
+          markdown_link_checker_sc -r ${{ github.workspace }} -d en -f ./docs/logs/prFiles.json -i assets -u docs.px4.io/main/ > ./docs/logs/errorsFilteredByPrPages.md
+          mkdir -p ./pr
+          cp ./docs/logs/errorsFilteredByPrPages.md ./pr/errorsFilteredByPrPages.md
+
+      - name: Read errorsFilteredByPrPages.md file
+        id: read-errors-by-page
+        uses: juliangruber/read-file-action@v1
+        with:
+          path: ./logs/errorsFilteredByPrPages.md
+
+      - name: Echo Errors by Page
+        run: echo "${{ steps.read-errors-by-page.outputs.content }}"
+
+      - name: Save PR number
+        env:
+          PR_NUMBER: ${{ github.event.number }}
+        run: |
+          #mkdir -p ./pr
+          echo $PR_NUMBER > ./pr/pr_number
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pr_number
+          path: pr/

.github/workflows/ekf_functional_change_indicator.yml

@@ -4,6 +4,9 @@ on:
   pull_request:
     branches:
     - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   unit_tests:

.github/workflows/ekf_update_change_indicator.yml

@@ -1,6 +1,10 @@
 name: EKF Update Change Indicator
 
-on: push
+on:
+  push:
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   unit_tests:

.github/workflows/failsafe_sim.yml

@@ -4,9 +4,15 @@ on:
   push:
     branches:
     - 'main'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
     - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   build:

.github/workflows/flash_analysis.yml

@@ -9,9 +9,15 @@ on:
   push:
     branches:
       - 'main'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
       - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 env:
   MIN_FLASH_POS_DIFF_FOR_COMMENT: 50

.github/workflows/mavros_mission_tests.yml

@@ -4,9 +4,15 @@ on:
   push:
     branches:
     - 'main'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
     - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   build:

.github/workflows/mavros_offboard_tests.yml

@@ -4,9 +4,15 @@ on:
   push:
     branches:
     - 'main'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
     - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   build:

.github/workflows/nuttx_env_config.yml

@@ -4,9 +4,15 @@ on:
   push:
     branches:
     - 'main'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
     - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   build:

.github/workflows/pr_comment.yml

@@ -0,0 +1,107 @@
+name: Docs - Comment Workflow
+on:
+  workflow_run:
+    workflows: ["Check for flaws"]
+    types:
+      - completed
+jobs:
+  comment:
+    permissions:
+      pull-requests: write # for marocchino/sticky-pull-request-comment
+    name: Comments
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Download PR artifact'
+        uses: actions/github-script@v6
+        with:
+          script: |
+            let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
+               owner: context.repo.owner,
+               repo: context.repo.repo,
+               run_id: context.payload.workflow_run.id,
+            });
+            let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
+              return artifact.name == "pr_number"
+            })[0];
+            let download = await github.rest.actions.downloadArtifact({
+               owner: context.repo.owner,
+               repo: context.repo.repo,
+               artifact_id: matchArtifact.id,
+               archive_format: 'zip',
+            });
+            let fs = require('fs');
+            fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/pr_number.zip`, Buffer.from(download.data));
+
+      - name: 'Unzip artifact'
+        run: unzip pr_number.zip
+
+      # Doesn't work across workflows
+      #- name: Get artifacts from flaw checker workflow
+      #  uses: actions/download-artifact@v3
+      #  with:
+      #    name: logs_and_errors
+      #    #path: ./logs
+
+      - name: Read errorsFilteredByPrPages.md file
+        id: read-errors-by-page
+        uses: juliangruber/read-file-action@v1
+        with:
+          path: ./errorsFilteredByPrPages.md
+
+      - name: Read PR number
+        id: read-error-pr-number
+        uses: juliangruber/read-file-action@v1
+        with:
+          path: ./pr_number
+
+      - name: File detail info
+        run: |
+          echo "${{ steps.read-errors-by-page.outputs.content }}"
+          echo "${{ steps.read-error-pr-number.outputs.content }}"
+
+      - name: Create or update comment
+        id: comment_to_pr
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          recreate: true
+          number: ${{ steps.read-error-pr-number.outputs.content }}
+          header: flaws
+          message: ${{ steps.read-errors-by-page.outputs.content || 'No flaws found' }}
+
+      #- name: Dump GitHub context
+      #  env:
+      #    GITHUB_CONTEXT: ${{ toJSON(github) }}
+      #  run: echo "$GITHUB_CONTEXT"
+
+      # Would like to do this, but it doesn't work (for me).
+      # Moving to time-based, or triggering on workflow
+      #- name: Wait for artifacts upload to succeed
+      #  uses: lewagon/wait-on-check-action@v1.3.1
+      #  with:
+      #    ref: ${{ github.ref }}
+      #    check-name: 'Archive production artifacts'
+      #    repo-token: ${{ secrets.GITHUB_TOKEN }}
+      #    wait-interval: 80
+
+      # Not needed for now - trying to trigger off the workflow
+      #- name: Sleep for 80 seconds
+      #  run: sleep 80s
+      #  shell: bash
+      #- name: Find Comment
+      #  uses: peter-evans/find-comment@v2
+      #  id: fc
+      #  with:
+      #    issue-number: ${{ steps.read-error-pr-number.outputs.content }}
+      #    comment-author: 'github-actions[bot]'
+      #    body-includes: Flaws (may be none)
+
+      #- name: Create or update comment
+      #  uses: peter-evans/create-or-update-comment@v3
+      #  with:
+      #    comment-id: ${{ steps.fc.outputs.comment-id }}
+      #    issue-number: ${{ steps.read-error-pr-number.outputs.content }}
+      #    body: |
+      #      Flaws (may be none)
+      #      ${{ steps.read-errors-by-page.outputs.content }}
+      #    edit-mode: replace

.github/workflows/python_checks.yml

@@ -4,9 +4,15 @@ on:
   push:
     branches:
     - 'main'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
     - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   build:

.github/workflows/ros_translation_node.yml

@@ -3,9 +3,15 @@ on:
   push:
     branches:
     - 'main'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
     - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 defaults:
   run:
     shell: bash

.github/workflows/sitl_tests.yml

@@ -9,9 +9,15 @@ on:
   push:
     branches:
     - 'main'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
   pull_request:
     branches:
     - '*'
+    paths-ignore:
+      - 'docs/**'
+      - '.github/**'
 
 jobs:
   build: