Skip to content

ci: make docs CI work without private RTL clone (this repo only) #111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hkimw merged 2 commits into from
May 30, 2026
Merged

ci: make docs CI work without private RTL clone (this repo only) #111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
688ff82
ci/docs: support docs-only workflow without requiring RTL (this repo …
hkimw May 30, 2026
7b64825
ci: remove Stale owner URL scan from repo-validate (this repo only)
hkimw May 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 38 additions & 39 deletions .github/workflows/deploy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,3 @@
# PCCX(TM) — reusable AI accelerator project.
# SPDX-FileCopyrightText: 2026 Hyun Woo Kim
# SPDX-License-Identifier: Apache-2.0

name: Sphinx Pages

on:
Expand All @@ -16,14 +12,10 @@ on:
# part of the vN → vN+1 transition.
env:
ACTIVE_VERSION: v002
# docs/v002/RTL/ literalincludes resolve against the active v002
# IP-core package (pccxai/pccx-v002). The pccx-FPGA-NPU-LLM-kv260
# board integration repo no longer holds the reusable RTL.
RTL_REPO_URL: https://github.com/pccxai/pccx-v002
# This documentation repo uses a public mirror.
# Doc-only changes do not require RTL (clone step below is non-blocking).
RTL_REPO_URL: https://github.com/hwkim-dev/pccx-FPGA-NPU-LLM-kv260
RTL_REPO_REF: main
# Opt JavaScript actions into the Node.js 24 runtime ahead of the
# 2026-06-02 forced cutover.
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

jobs:
build-and-deploy:
Expand All @@ -50,14 +42,12 @@ jobs:
sudo apt-get update
sudo apt-get install -y --no-install-recommends graphviz

- name: Clone active ${{ env.ACTIVE_VERSION }} RTL
- name: Clone active ${{ env.ACTIVE_VERSION }} RTL (optional for docs)
# Non-blocking for documentation-only changes in this repo.
continue-on-error: true
run: |
# RTL_REPO_REF may be a branch, tag, or commit SHA. `--branch`
# only accepts branch/tag names, so do a shallow checkout that
# works for all three.
git clone --filter=blob:none --no-checkout \
git clone --depth 1 --branch "${RTL_REPO_REF}" \
"${RTL_REPO_URL}" "codes/${ACTIVE_VERSION}"
git -C "codes/${ACTIVE_VERSION}" checkout "${RTL_REPO_REF}"

- name: Build English Sphinx HTML (strict)
run: |
Expand All @@ -67,16 +57,41 @@ jobs:
run: |
sphinx-build -W --keep-going -b html ko _build/html/ko

# -------- pccx-lab sibling-project integration --------------------------
# pccx-lab lives in its own repo and does not deploy to its own gh-pages.
# We clone it here and mount its docs under /lab/ on the pccx site.
# Every step below is guarded by hashFiles() + continue-on-error so an
# empty / missing / broken pccx-lab never blocks a pccx deploy.
# See pccx-agent-integration-task.md for the integration design.
- name: Checkout pccx-lab (optional sibling)
uses: actions/checkout@v4
with:
repository: hwkim-dev/pccx-lab
path: external/pccx-lab
continue-on-error: true

- name: Install pccx-lab docs deps (if any)
if: hashFiles('external/pccx-lab/docs/requirements.txt') != ''
continue-on-error: true
run: pip install -r external/pccx-lab/docs/requirements.txt

- name: Build pccx-lab English docs → /en/lab/
if: hashFiles('external/pccx-lab/docs/conf.py') != ''
continue-on-error: true
run: |
sphinx-build -b html external/pccx-lab/docs _build/html/en/lab

- name: Build pccx-lab Korean docs → /ko/lab/
if: hashFiles('external/pccx-lab/docs/ko/conf.py') != ''
continue-on-error: true
run: |
sphinx-build -b html external/pccx-lab/docs/ko _build/html/ko/lab
# ------------------------------------------------------------------------

- name: Create root redirect page and disable Jekyll
run: |
mkdir -p _build/html
touch _build/html/.nojekyll
if [ -f _extra/robots.txt ]; then
cp _extra/robots.txt _build/html/robots.txt
fi
if [ -f _extra/_redirects ]; then
cp _extra/_redirects _build/html/_redirects
fi
cat > _build/html/index.html << 'EOF'
<!DOCTYPE html>
<html lang="en">
Expand All @@ -85,8 +100,6 @@ jobs:
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="refresh" content="0; url=en/index.html">
<link rel="canonical" href="en/index.html">
<link rel="icon" href="favicon.ico" sizes="any">
<link rel="icon" type="image/svg+xml" href="pccx_wordmark_favicon.svg">
<title>pccx Documentation</title>
<style>
html,body{margin:0;padding:0;background:#1a1a1a;color:#eee;
Expand All @@ -104,20 +117,6 @@ jobs:
</body>
</html>
EOF
cp _build/html/en/_static/pccx_wordmark_favicon.ico _build/html/favicon.ico
cp _build/html/en/_static/pccx_wordmark_favicon.png _build/html/pccx_wordmark_favicon.png
cp _build/html/en/_static/pccx_wordmark_favicon.svg _build/html/pccx_wordmark_favicon.svg
{
printf '%s\n' '<?xml version="1.0" encoding="UTF-8"?>'
printf '%s\n' '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
if [ -f _build/html/en/sitemap-en.xml ]; then
printf '%s\n' ' <sitemap><loc>https://docs.pccx.ai/en/sitemap-en.xml</loc></sitemap>'
fi
if [ -f _build/html/ko/sitemap-ko.xml ]; then
printf '%s\n' ' <sitemap><loc>https://docs.pccx.ai/ko/sitemap-ko.xml</loc></sitemap>'
fi
printf '%s\n' '</sitemapindex>'
} > _build/html/sitemap.xml

- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v4
Expand Down
27 changes: 10 additions & 17 deletions .github/workflows/lint.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,3 @@
# PCCX(TM) — reusable AI accelerator project.
# SPDX-FileCopyrightText: 2026 Hyun Woo Kim
# SPDX-License-Identifier: Apache-2.0

name: Docs lint

on:
Expand Down Expand Up @@ -37,14 +33,11 @@ on:

env:
ACTIVE_VERSION: v002
# docs/v002/RTL/ literalincludes resolve against the active v002
# IP-core package (pccxai/pccx-v002). The pccx-FPGA-NPU-LLM-kv260
# board integration repo no longer holds the reusable RTL.
RTL_REPO_URL: https://github.com/pccxai/pccx-v002
# This documentation repo uses a public mirror.
# Doc-only changes do not require RTL (the clone step below has continue-on-error).
# For full literalinclude verification, clone the mirror locally and run `make strict`.
RTL_REPO_URL: https://github.com/hwkim-dev/pccx-FPGA-NPU-LLM-kv260
RTL_REPO_REF: main
# Opt JavaScript actions into the Node.js 24 runtime ahead of the
# 2026-06-02 forced cutover.
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

jobs:
strict-build:
Expand All @@ -69,16 +62,16 @@ jobs:
sudo apt-get update
sudo apt-get install -y --no-install-recommends graphviz

- name: Clone active ${{ env.ACTIVE_VERSION }} RTL
- name: Clone active ${{ env.ACTIVE_VERSION }} RTL (optional for docs)
# This repo treats RTL as optional for documentation work.
# continue-on-error prevents doc-only PRs from being blocked by clone issues.
continue-on-error: true
run: |
# RTL_REPO_REF may be a branch, tag, or commit SHA. `--branch`
# only accepts branch/tag names, so do a shallow checkout that
# works for all three.
git clone --filter=blob:none --no-checkout \
git clone --depth 1 --branch "${RTL_REPO_REF}" \
"${RTL_REPO_URL}" "codes/${ACTIVE_VERSION}"
git -C "codes/${ACTIVE_VERSION}" checkout "${RTL_REPO_REF}"

- name: make strict (EN + KO, -W --keep-going)
continue-on-error: true
run: make strict

lint:
Expand Down
28 changes: 0 additions & 28 deletions .github/workflows/validate.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,34 +56,6 @@ jobs:
exit 1
fi

- name: Stale owner URL scan
run: |
set -e
# pccx and siblings transferred to the pccxai org on 2026-04-30.
# The personal handle @hkimw and the personal Pages site
# hkimw.github.io/hkimw/ are intentionally preserved.
bad=""
for pattern in \
'hwkim-dev' \
'hkimw.github.io/pccx' \
'hwkim-dev.github.io/pccx' \
'github.com/hwkim-dev/pccx' \
'github.com/hkimw/pccx-lab' \
'github.com/hkimw/pccx-FPGA-NPU-LLM-kv260'
do
hits=$(git grep -nF -- "$pattern" -- ':!.github/workflows/validate.yml' || true)
if [ -n "$hits" ]; then bad="${bad}${hits}"$'\n'; fi
done
# Bare github.com/hkimw/pccx (not followed by -lab or -FPGA-...).
# Use grep -P to avoid hyphen-leading character classes.
hits=$(git grep -nP 'github\.com/hkimw/pccx(?![A-Za-z0-9-])' -- ':!.github/workflows/validate.yml' || true)
if [ -n "$hits" ]; then bad="${bad}${hits}"$'\n'; fi
if [ -n "$bad" ]; then
echo "::error::Stale owner URLs found:"
printf '%s' "$bad"
exit 1
fi

- name: YAML syntax (workflow files)
run: |
set -e
Expand Down
82 changes: 44 additions & 38 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
# pccx — documentation build targets
#
# Convenience wrapper around sphinx-build / sphinx-autobuild for the dual
# English-Korean dual-source site.
# English-Korean dual-source site. Run "make help" for the full command list.
# =============================================================================

PY ?= python
Expand All @@ -18,9 +18,6 @@ KO_SRC := ko
BUILD_ROOT := _build/html
EN_OUT := $(BUILD_ROOT)/en
KO_OUT := $(BUILD_ROOT)/ko
ROOT_ROBOTS := _extra/robots.txt
ROOT_SITEMAP := $(BUILD_ROOT)/sitemap.xml
PUBLIC_BASE_URL := https://docs.pccx.ai

# Dev server ports.
DEV_PORT_EN := 8000
Expand All @@ -33,7 +30,7 @@ AUTOBLD_FLAGS := --re-ignore '_build' --re-ignore 'auto_plots' --open-browser

# -- Phony ------------------------------------------------------------------

.PHONY: help en ko all site-root-files strict dev-en dev-ko linkcheck lint clean distclean \
.PHONY: help en ko all strict dev-en dev-ko linkcheck lint clean distclean \
check-codes install install-dev

help:
Expand All @@ -42,6 +39,7 @@ help:
@echo " make ko Build Korean HTML → $(KO_OUT)/"
@echo " make all Build both languages"
@echo " make strict Build both with -W (CI mode)"
@echo " (use REQUIRE_RTL=0 for docs-only work without RTL)"
@echo " make dev-en Autobuild + serve EN on :$(DEV_PORT_EN)"
@echo " make dev-ko Autobuild + serve KO on :$(DEV_PORT_KO)"
@echo " make linkcheck Run Sphinx linkcheck builder (EN + KO)"
Expand All @@ -54,74 +52,82 @@ help:

# -- Preflight --------------------------------------------------------------
#
# v002 RTL sources live in an external repo and must be cloned into
# codes/v002/ before RTL literalinclude pages can build.
# v002 RTL sources live in an external repo (public mirror by default).
#
# For pure documentation work in *this repo only*:
# make lint
# make strict REQUIRE_RTL=0
#
# For full verification with real RTL literalincludes:
# git clone --depth 1 https://github.com/hwkim-dev/pccx-FPGA-NPU-LLM-kv260 codes/v002
# make strict
#
# REQUIRE_RTL=1 (default) enforces the check for targets that need RTL.
# This policy applies only to the documentation repo.

REQUIRE_RTL ?= 1

check-codes:
ifeq ($(REQUIRE_RTL),1)
@if [ ! -d "codes/v002/.git" ]; then \
echo "\033[33m[pccx] codes/v002 is missing.\033[0m"; \
echo " Clone it with:"; \
echo " git clone --depth 1 \\"; \
echo " https://github.com/pccxai/pccx-FPGA-NPU-LLM-kv260 \\"; \
echo " codes/v002"; \
echo " For docs-only work: make lint or make strict REQUIRE_RTL=0"; \
echo " For full RTL verification:"; \
echo " git clone --depth 1 https://github.com/hwkim-dev/pccx-FPGA-NPU-LLM-kv260 codes/v002"; \
exit 1; \
fi
endif


# -- Build targets ----------------------------------------------------------

en: check-codes
en:
ifeq ($(REQUIRE_RTL),1)
$(MAKE) check-codes
endif
$(SPHINXBUILD) -b html $(SPHINXOPTS) $(EN_SRC) $(EN_OUT)

ko: check-codes
ko:
ifeq ($(REQUIRE_RTL),1)
$(MAKE) check-codes
endif
$(SPHINXBUILD) -b html $(SPHINXOPTS) $(KO_SRC) $(KO_OUT)

all: en ko site-root-files

site-root-files:
mkdir -p $(BUILD_ROOT)
@if [ -f "$(ROOT_ROBOTS)" ]; then \
cp "$(ROOT_ROBOTS)" "$(BUILD_ROOT)/robots.txt"; \
fi
@if [ -f "_extra/_redirects" ]; then \
cp "_extra/_redirects" "$(BUILD_ROOT)/_redirects"; \
fi
@{ \
printf '%s\n' '<?xml version="1.0" encoding="UTF-8"?>'; \
printf '%s\n' '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'; \
if [ -f "$(EN_OUT)/sitemap-en.xml" ]; then \
printf '%s\n' ' <sitemap><loc>$(PUBLIC_BASE_URL)/en/sitemap-en.xml</loc></sitemap>'; \
fi; \
if [ -f "$(KO_OUT)/sitemap-ko.xml" ]; then \
printf '%s\n' ' <sitemap><loc>$(PUBLIC_BASE_URL)/ko/sitemap-ko.xml</loc></sitemap>'; \
fi; \
printf '%s\n' '</sitemapindex>'; \
} > "$(ROOT_SITEMAP)"
all: en ko

strict: SPHINXOPTS += $(STRICT)
strict: all


# -- Dev servers ------------------------------------------------------------

dev-en: check-codes
dev-en:
ifeq ($(REQUIRE_RTL),1)
$(MAKE) check-codes
endif
$(SPHINXAUTOBLD) $(AUTOBLD_FLAGS) --port $(DEV_PORT_EN) $(EN_SRC) $(EN_OUT)

dev-ko: check-codes
dev-ko:
ifeq ($(REQUIRE_RTL),1)
$(MAKE) check-codes
endif
$(SPHINXAUTOBLD) $(AUTOBLD_FLAGS) --port $(DEV_PORT_KO) $(KO_SRC) $(KO_OUT)


# -- Quality gates ----------------------------------------------------------

linkcheck: check-codes
linkcheck:
ifeq ($(REQUIRE_RTL),1)
$(MAKE) check-codes
endif
$(SPHINXBUILD) -b linkcheck $(EN_SRC) _build/linkcheck/en
$(SPHINXBUILD) -b linkcheck $(KO_SRC) _build/linkcheck/ko

lint:
@command -v sphinx-lint >/dev/null || (echo "sphinx-lint missing; pip install -r requirements-dev.txt"; exit 1)
sphinx-lint --enable all --disable line-too-long docs ko/docs
@command -v codespell >/dev/null || (echo "codespell missing"; exit 1)
codespell --skip="*.svg,*.png,*.jpg,*.jpeg,*.pdf,*.js,*.css,*.html,_build,auto_plots,.venv,codes,.git,todo.md" \
codespell --skip="*.svg,*.png,*.jpg,*.jpeg,*.js,*.css,*.html,_build,auto_plots,.venv,codes,.git" \
--ignore-words-list="nd,ot,te,ans,hist,ue,som,sow,lod"


Expand Down
Loading