Mirrors_Framework/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-05-24 23:55:24 +08:00
Code Issues Actions 7 Packages Projects Releases Wiki Activity

docs: consolidate docs ci

Browse Source 
adds docs

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
This commit is contained in:
Ramon Roche
2026-02-06 11:39:59 -08:00
parent 0efded2fa7
commit 2290096e25
6 changed files with 233 additions and 368 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/docs-orchestrator.yml
+48 -5
View File
@@ -16,6 +16,7 @@ permissions:
contents: write
actions: read
id-token: write
pull-requests: write
concurrency:
group: docs-orchestrator-${{ github.ref }}
@@ -203,6 +204,7 @@ jobs:
uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
- name: Download metadata artifact
if: needs.pr-metadata-regen.result == 'success'
@@ -211,15 +213,47 @@ jobs:
name: pr-metadata
path: docs/
- name: Get changed doc files
id: changed-files
uses: tj-actions/changed-files@v46.0.5
with:
json: true
base_sha: ${{ github.event.pull_request.base.sha }}
sha: ${{ github.event.pull_request.head.sha }}
files: |
docs/en/**/*.md
- name: Save changed files list
run: |
mkdir -p logs
echo '${{ steps.changed-files.outputs.all_changed_files }}' | jq '.' > ./logs/prFiles.json
echo "Changed files:"
cat ./logs/prFiles.json
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
- name: Run link checker
- name: Run filtered link checker (changed files)
run: |
npm -g install markdown_link_checker_sc@0.0.138
mkdir -p logs
if [ "$(jq length ./logs/prFiles.json)" -gt 0 ]; then
markdown_link_checker_sc \
-r "$GITHUB_WORKSPACE" \
-d docs \
-e en \
-f ./logs/prFiles.json \
-i assets \
-u docs.px4.io/main/ \
> ./logs/filtered-link-check-results.md || true
else
echo "No changed doc files found" > ./logs/filtered-link-check-results.md
fi
cat ./logs/filtered-link-check-results.md
- name: Run full link checker
run: |
markdown_link_checker_sc \
-r "$GITHUB_WORKSPACE" \
-d docs \
@@ -229,11 +263,17 @@ jobs:
> ./logs/link-check-results.md || true
cat ./logs/link-check-results.md
- name: Post PR comment with link check results
uses: marocchino/sticky-pull-request-comment@v2
with:
header: flaws
path: ./logs/filtered-link-check-results.md
- name: Upload link check results
uses: actions/upload-artifact@v4
with:
name: link-check-results
path: logs/link-check-results.md
path: logs/
retention-days: 7
# =============================================================================
@@ -241,8 +281,11 @@ jobs:
# =============================================================================
build-site:
name: "Build Site"
needs: [detect-changes, pr-metadata-regen, metadata-regen]
if: always() && (needs.metadata-regen.result == 'success' || needs.metadata-regen.result == 'skipped')
needs: [detect-changes, pr-metadata-regen, metadata-regen, link-check]
if: >-
always() &&
(needs.metadata-regen.result == 'success' || needs.metadata-regen.result == 'skipped') &&
(needs.link-check.result == 'success' || needs.link-check.result == 'skipped')
runs-on: [runs-on,runner=4cpu-linux-x64,image=ubuntu24-full-x64,"run-id=${{ github.run_id }}",spot=false,extras=s3-cache]
outputs:
branchname: ${{ steps.set-branch.outputs.branchname }}
.github/workflows/docs_deploy_aws.yml
-116
View File
@@ -1,116 +0,0 @@
name: Docs - Deploy PX4 User Guide to AWS
on:
push:
branches:
- "main"
- "release/**"
paths:
- "docs/en/**"
- "docs/zh/**"
- "docs/uk/**"
- "docs/ko/**"
pull_request:
paths:
- "docs/en/**"
- "docs/zh/**"
- "docs/uk/**"
- "docs/ko/**"
workflow_dispatch:
permissions:
contents: read
actions: read
id-token: write # for AWS OIDC
concurrency:
group: docs-deploy
cancel-in-progress: false
jobs:
build:
runs-on: [runs-on,runner=4cpu-linux-x64,image=ubuntu24-full-x64,"run-id=${{ github.run_id }}",spot=false,extras=s3-cache]
outputs:
branchname: ${{ steps.set-branch.outputs.branchname }}
releaseversion: ${{ steps.set-version.outputs.releaseversion }}
steps:
- uses: runs-on/action@v1
- name: Checkout
uses: actions/checkout@v4
- id: set-branch
run: echo "branchname=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_OUTPUT
- id: set-version
run: |
branch="${{ steps.set-branch.outputs.branchname }}"
if [[ "$branch" == "main" ]]; then
version="main"
else
version="v${branch#release/}"
fi
echo "releaseversion=$version" >> $GITHUB_OUTPUT
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
cache-dependency-path: ./docs/yarn.lock
- name: Install dependencies
run: yarn install --frozen-lockfile --cwd ./docs
- name: Build with VitePress
working-directory: ./docs
env:
BRANCH_NAME: ${{ steps.set-version.outputs.releaseversion }}
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: ubuntu-latest
steps:
- name: Download Artifact
uses: actions/download-artifact@v4
with:
name: px4_docs_build
path: ~/_book
- name: Configure AWS from OIDC
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
aws-region: us-west-2
- name: Sanity check AWS credentials
run: aws sts get-caller-identity
- name: Upload HTML with short cache
run: |
aws s3 sync ~/_book/ s3://px4-docs/${{ needs.build.outputs.releaseversion }}/ \
--delete \
--exclude "*" --include "*.html" \
--cache-control "public, max-age=60"
- name: Upload assets with long cache
run: |
aws s3 sync ~/_book/ s3://px4-docs/${{ needs.build.outputs.releaseversion }}/ \
--delete \
--exclude "*.html" \
--cache-control "public, max-age=86400, immutable"
.github/workflows/docs_flaw_checker.yml
-86
View File
@@ -1,86 +0,0 @@
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 }}
fetch-depth: 0
- name: Install Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Create logs directory
run: |
mkdir logs
- name: Get changed english doc files
id: get_changed_markdown_english
uses: tj-actions/changed-files@v46.0.5
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 "$ALL_CHANGED_FILES"
# echo "$ALL_CHANGED_FILES" > ./logs/prFiles.json
echo "$ALL_CHANGED_FILES" | sed 's/\\//g' | jq '.' > ./logs/prFiles.json
env:
ALL_CHANGED_FILES: ${{ steps.get_changed_markdown_english.outputs.all_changed_files }}
- name: Run link checker
id: link-check
run: |
npm -g install markdown_link_checker_sc@0.0.138
markdown_link_checker_sc \
-r "$GITHUB_WORKSPACE" \
-d docs \
-e en \
-f ./logs/prFiles.json \
-i assets \
-u docs.px4.io/main/ \
> ./logs/errorsFilteredByPrPages.md
mkdir -p ./pr
cp ./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 "$ERRORS"
env:
ERRORS: ${{ steps.read-errors-by-page.outputs.content }}
- name: Save PR number
run: echo "$PR_NUMBER" > ./pr/pr_number
env:
PR_NUMBER: ${{ github.event.number }}
- uses: actions/upload-artifact@v4
with:
name: pr_number
path: pr/
.github/workflows/docs_metadata_check.yml
-49
View File
@@ -1,49 +0,0 @@
name: Docs Metadata Checks
permissions:
contents: write
on:
pull_request: {}
push:
branches:
- main
- 'release/**'
jobs:
metadata-check:
name: ${{ matrix.name }} metadata
runs-on: [runs-on,runner=2cpu-linux-x64,image=ubuntu24-full-x64,"run-id=${{ github.run_id }}",spot=true]
container:
image: ghcr.io/px4/px4-dev:v1.16.0-ondemand
strategy:
fail-fast: false
matrix:
include:
- name: uORB Graphs
script: Tools/ci/metadata_uorb_graph.sh
# - name: Failsafe Web
# script: Tools/ci/metadata_failsafe_web.sh
- name: uORB Messages
script: Tools/ci/metadata_msg_docs.sh
- name: Parameter Reference
script: Tools/ci/metadata_parameters.sh
- name: Airframe Reference
script: Tools/ci/metadata_airframe.sh
- name: Module Reference
script: Tools/ci/metadata_modules.sh
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
persist-credentials: true
- name: Mark all directories safe for Git
run: git config --system --add safe.directory '*'
- name: Run ${{ matrix.name }} metadata check
run: ${{ matrix.script }} --test-only
- name: Setup tmate session
if: ${{ failure() }}
uses: mxschmitt/action-tmate@v3
.github/workflows/docs_pr_comment.yml
-111
View File
@@ -1,111 +0,0 @@
name: Docs - Comment Workflow
on:
workflow_run:
workflows: ["Docs - Check for flaws in PX4 Guide Source"]
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 "$ERRORS"
echo "$PRNUM"
env:
ERRORS: ${{ steps.read-errors-by-page.outputs.content }}
PRNUM: ${{ 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
docs/en/test_and_ci/continous_integration.md
+185 -1
View File
@@ -1,3 +1,187 @@
# PX4 Continuous Integration
PX4 builds and testing are performed using GitHub actions and a Jenkins server.
PX4 uses GitHub Actions for continuous integration, with different workflows handling code builds, testing, and documentation.
## Documentation CI
The documentation pipeline handles building, deploying, and translating the PX4 User Guide.
All documentation CI is consolidated into a single orchestrator workflow organized in tiers.
### Docs Orchestrator
**Workflow file:** [`docs-orchestrator.yml`](https://github.com/PX4/PX4-Autopilot/blob/main/.github/workflows/docs-orchestrator.yml)
This is the main documentation workflow. It runs on pull requests and pushes to `main` and `release/**` branches, performing different jobs depending on the trigger event.
Jobs are organized in tiers, where each tier depends on the previous one completing successfully.
#### Tier Structure
| Tier | Job | PR | Push | Description |
|------|-----|----|------|-------------|
| 0 | Detect Changed Paths | Yes | — | Checks if source code files changed (triggers metadata regen) |
| 1 | Metadata Generation | Yes (conditional) | Yes | Builds PX4 SITL and regenerates all auto-generated docs |
| 2 | Link Validation | Yes | — | Checks for broken links in changed files, posts PR comment |
| 3 | Build Site | Yes (gated on Tier 2) | Yes (after Tier 1) | Builds the VitePress documentation site |
| 4 | Deploy + Crowdin Upload | — | Yes | Deploys to AWS S3 and uploads sources to Crowdin |
#### Pull Request Flow
When a PR modifies files in `docs/**`, the workflow validates the changes:
```
PR Event
│
▼
┌─────────────────────────────────────┐
│ Tier 0: Detect Changed Paths │
│ • Checks if src/msg/ROMFS changed │
└─────────────────┬───────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Tier 1: PR Metadata Regen │
│ (only if source files changed) │
│ • Builds px4_sitl_default │
│ • Generates parameter/airframe/ │
│ module documentation │
│ • Builds failsafe web simulator │
└─────────────────┬───────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Tier 2: Link Validation (~30 sec) │
│ • Detects changed docs/en/*.md │
│ • Runs filtered link check │
│ • Posts sticky PR comment (flaws) │
│ • Runs full link check (artifact) │
└─────────────────┬───────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Tier 3: Build Site (~7-10 min) │
│ (only if link check passed) │
│ • Builds VitePress site │
│ • Verifies no build errors │
└─────────────────┬───────────────────┘
│
▼
DONE
```
| Job | Duration | Description |
|-----|----------|-------------|
| **Detect Changed Paths** | ~10s | Determines if metadata regeneration is needed |
| **PR Metadata Regen** | ~10-15m | Rebuilds PX4 SITL and regenerates all metadata (conditional) |
| **Link Validation** | ~30s | Checks for broken links in changed markdown files and posts a sticky comment to the PR |
| **Build Site** | ~7-10m | Builds the VitePress site to verify there are no build errors. Gated on link check passing. |
#### Push Flow (main/release branches)
When changes are pushed to `main` or `release/**` branches, the workflow regenerates metadata, builds, and deploys:
```
Push Event
│
▼
┌─────────────────────────────────────┐
│ Tier 1: Regenerate Metadata │
│ (~10-15 min) │
│ • Builds px4_sitl_default │
│ • Generates parameter/airframe/ │
│ module documentation │
│ • Builds failsafe web simulator │
│ • Formats with Prettier │
│ • Auto-commits if changes detected │
└─────────────────┬───────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Tier 3: Build Site (~7-10 min) │
│ • Builds VitePress site │
│ • Uploads build artifact │
└─────────────────┬───────────────────┘
│
┌───────┴───────┐
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ Tier 4: │ │ Tier 4: │
│ Deploy to │ │ Crowdin Upload │
│ AWS (~3 min) │ │ (~4 min) │
│ • S3 sync │ │ • Upload sources │
└──────────────┘ └──────────────────┘
```
| Job | Duration | Description |
|-----|----------|-------------|
| **Regenerate Metadata** | ~10-15m | Rebuilds PX4 SITL, regenerates all metadata, formats with Prettier, auto-commits |
| **Build Site** | ~7-10m | Builds the VitePress documentation site |
| **Deploy to AWS** | ~3m | Syncs built site to AWS S3 (HTML: 60s cache, assets: 24h cache) |
| **Crowdin Upload** | ~4m | Uploads English source files to Crowdin for translation (main branch only) |
#### Generated Metadata
The metadata regeneration job creates the following auto-generated documentation:
| Type | Output | Description |
|------|--------|-------------|
| Parameters | `docs/en/advanced_config/parameter_reference.md` | Complete parameter reference |
| Airframes | `docs/en/airframes/airframe_reference.md` | Airframe configurations |
| Modules | `docs/en/modules/*.md` | Module documentation |
| Messages | `docs/en/msg_docs/*.md` | uORB message documentation |
| uORB Graphs | `docs/public/middleware/*.json` | Topic dependency graphs |
| Failsafe Simulator | `docs/public/config/failsafe/*` | Interactive failsafe simulator (WebAssembly) |
::: warning
Do not manually edit the auto-generated files listed above. They are overwritten on every push to main.
:::
#### Path Triggers
The workflow triggers on changes to these paths:
| Path | Reason |
|------|--------|
| `docs/**` | Documentation source files |
| `src/**` | Source code changes affect metadata |
| `msg/**` | Message definitions affect metadata |
| `ROMFS/**` | ROMFS files affect metadata |
| `Tools/module_config/**` | Module configuration affects metadata |
### Crowdin Download Workflow
**Workflow file:** [`docs_crowdin_download.yml`](https://github.com/PX4/PX4-Autopilot/blob/main/.github/workflows/docs_crowdin_download.yml)
This scheduled workflow downloads completed translations from Crowdin and creates pull requests.
| Setting | Value |
|---------|-------|
| **Schedule** | Every Sunday at 00:00 UTC |
| **Target Languages** | Korean (ko), Ukrainian (uk), Chinese Simplified (zh-CN) |
**Process:**
1. Downloads translations for each target language from Crowdin
2. Creates a separate PR for each language with new translations
3. PRs are labeled "Documentation" and assigned for review
### Caching Strategy
The workflows use caching to speed up builds:
| Cache | Size | Purpose |
|-------|------|---------|
| ccache | 1GB | C++ compilation cache for SITL builds |
| node_modules | ~26MB | Node.js dependencies for VitePress |
### Infrastructure
Jobs run on [runs-on](https://runs-on.com/) self-hosted runners with S3 cache:
| Job | Runner |
|-----|--------|
| Detect Changed Paths | ubuntu-latest |
| Link Validation | ubuntu-latest |
| Metadata Regen | 4 CPU (with px4-dev container) |
| Build Site | 4 CPU |
| Deploy to AWS | ubuntu-latest |
| Crowdin Upload | ubuntu-latest |