Skip to content

Commit 116eba7

Browse files
oberstetoberstet
committed
Fix GitHub release artifact integration to use correct target directory
The docs-integrate-github-release recipe was incorrectly copying artifacts to docs/_static/ (the source directory for manually committed static files). This is wrong because docs/_static/ should only contain files that are checked into version control. Changes: - Update docs-integrate-github-release to copy artifacts to docs/_build/html/_static/ (the built documentation directory) - Add validation check to ensure docs are built before integration - Update pre-release checklist Section 7 to clarify correct workflow order: build docs first, then integrate artifacts, then view - Fix conformance.rst links to include with-nvx/ and without-nvx/ subdirectories in paths - Update conformance documentation to show both NVX and non-NVX test results separately The correct workflow is now: 1. just docs (build documentation) 2. just docs-integrate-github-release (integrate downloaded artifacts into built docs) 3. just docs-view (view the complete documentation) This ensures artifacts are only in the build output, never in the source tree.
1 parent 34551da commit 116eba7

3 files changed

Lines changed: 91 additions & 36 deletions

File tree

‎.audit/PRE_RELEASE_CHECKLIST-v25.10.1.md‎

Lines changed: 40 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -507,7 +507,7 @@ To use these artifacts:
507507
```
508508

509509
**Note:** These artifacts are used during RTD builds via `.github/scripts/rtd-download-artifacts.sh`.
510-
For local testing, use `just docs-integrate-github-release` to copy them into the docs build directory.
510+
For local testing, follow Section 7 below to build docs and integrate artifacts.
511511

512512
**Troubleshooting:**
513513

@@ -516,23 +516,55 @@ If downloads fail:
516516
2. Verify the artifact names match the release (especially for nightly vs stable)
517517
3. For older releases (before v25.10.1), these artifacts may not exist - use a newer nightly release
518518

519-
## 7. Documentation Build
519+
## 7. Documentation Build and Integration
520520

521-
Build the documentation locally:
521+
Build the documentation locally, then integrate the downloaded GitHub release artifacts:
522522

523523
```bash
524+
# Step 1: Build documentation
524525
just docs
526+
527+
# Step 2: Integrate downloaded artifacts into built docs
528+
just docs-integrate-github-release
529+
530+
# Step 3: View documentation
531+
just docs-view
525532
```
526533

527-
**Expected:** Build completes successfully (some warnings about missing artifacts OK).
534+
**Expected output from integration:**
528535

529-
Open docs for visual inspection:
536+
```
537+
==> No release tag specified. Finding latest downloaded artifacts...
538+
✅ Found latest downloaded artifacts: master-202510180103
539+
==> Integrating GitHub release artifacts into built documentation...
540+
Release: master-202510180103
541+
Source: /tmp/autobahn-release-artifacts-master-202510180103
542+
Target: docs/_build/html/_static/
530543
531-
```bash
532-
just docs-view
544+
==> Creating target directories in docs/_build/html/_static/...
545+
==> Copying conformance reports (with NVX)...
546+
✅ Copied 2954 files to docs/_build/html/_static/websocket/conformance/with-nvx/
547+
==> Copying conformance reports (without NVX)...
548+
✅ Copied 4430 files to docs/_build/html/_static/websocket/conformance/without-nvx/
549+
==> Copying FlatBuffers source schemas (.fbs)...
550+
⚠️ No .fbs files found in /tmp/autobahn-release-artifacts-master-202510180103
551+
==> Copying FlatBuffers binary schemas (.bfbs)...
552+
⚠️ No .bfbs files found in /tmp/autobahn-release-artifacts-master-202510180103
553+
==> Copying FlatBuffers schema directories...
554+
✅ Copied schema directories
555+
556+
════════════════════════════════════════════════════════════
557+
✅ GitHub release artifacts integrated into built documentation
558+
════════════════════════════════════════════════════════════
559+
560+
Integrated artifacts from: master-202510180103
561+
Target location: docs/_build/html/_static/
533562
```
534563

535-
This opens `docs/_build/html/index.html` in your browser.
564+
**Important:** The workflow order is critical:
565+
1. **Build docs first** (`just docs`) - Creates `docs/_build/html/` structure
566+
2. **Then integrate artifacts** (`just docs-integrate-github-release`) - Copies conformance reports and schemas into the built docs
567+
3. **Then view** (`just docs-view`) - Opens browser to review integrated documentation
536568

537569
### 7.1 Docs: Release Notes
538570

‎docs/websocket/conformance.rst‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,14 +25,24 @@ The latest conformance test results are generated automatically by our CI/CD pip
2525
Client Conformance
2626
~~~~~~~~~~~~~~~~~~
2727

28-
* `Client Results <../_static/websocket/conformance/clients/index.html>`__ - Autobahn|Python WebSocket client conformance
29-
* :download:`Client Results (JSON) Archive </_static/websocket/conformance/autobahn-python-websocket-client-conformance.zip>`
28+
**With NVX Acceleration:**
29+
30+
* `Client Results (With NVX) <../_static/websocket/conformance/with-nvx/clients/index.html>`__ - Autobahn|Python WebSocket client conformance with NVX acceleration
31+
32+
**Without NVX Acceleration:**
33+
34+
* `Client Results (Without NVX) <../_static/websocket/conformance/without-nvx/clients/index.html>`__ - Autobahn|Python WebSocket client conformance without NVX acceleration
3035

3136
Server Conformance
3237
~~~~~~~~~~~~~~~~~~~
3338

34-
* `Server Results <../_static/websocket/conformance/servers/index.html>`__ - Autobahn|Python WebSocket server conformance
35-
* :download:`Server Results (JSON) Archive </_static/websocket/conformance/autobahn-python-websocket-server-conformance.zip>`
39+
**With NVX Acceleration:**
40+
41+
* `Server Results (With NVX) <../_static/websocket/conformance/with-nvx/servers/index.html>`__ - Autobahn|Python WebSocket server conformance with NVX acceleration
42+
43+
**Without NVX Acceleration:**
44+
45+
* `Server Results (Without NVX) <../_static/websocket/conformance/without-nvx/servers/index.html>`__ - Autobahn|Python WebSocket server conformance without NVX acceleration
3646

3747
Running Tests Locally
3848
----------------------

‎justfile‎

Lines changed: 37 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1393,6 +1393,19 @@ docs-integrate-github-release release_tag="":
13931393

13941394
RELEASE_TAG="{{ release_tag }}"
13951395

1396+
# Check that docs have been built first
1397+
if [ ! -d "docs/_build/html" ]; then
1398+
echo "❌ ERROR: Documentation not built yet"
1399+
echo ""
1400+
echo "Please build documentation first using:"
1401+
echo " just docs"
1402+
echo ""
1403+
echo "Then integrate artifacts with:"
1404+
echo " just docs-integrate-github-release"
1405+
echo ""
1406+
exit 1
1407+
fi
1408+
13961409
# If no tag specified, find the most recently downloaded artifacts
13971410
if [ -z "${RELEASE_TAG}" ]; then
13981411
echo "==> No release tag specified. Finding latest downloaded artifacts..."
@@ -1425,33 +1438,34 @@ docs-integrate-github-release release_tag="":
14251438
exit 1
14261439
fi
14271440

1428-
echo "==> Integrating GitHub release artifacts into docs build..."
1441+
echo "==> Integrating GitHub release artifacts into built documentation..."
14291442
echo " Release: ${RELEASE_TAG}"
14301443
echo " Source: ${DOWNLOAD_DIR}"
1444+
echo " Target: docs/_build/html/_static/"
14311445
echo ""
14321446

1433-
# Create target directories
1434-
echo "==> Creating target directories in docs/_static/..."
1435-
mkdir -p docs/_static/websocket/conformance/with-nvx
1436-
mkdir -p docs/_static/websocket/conformance/without-nvx
1437-
mkdir -p docs/_static/flatbuffers
1447+
# Create target directories in the BUILT docs
1448+
echo "==> Creating target directories in docs/_build/html/_static/..."
1449+
mkdir -p docs/_build/html/_static/websocket/conformance/with-nvx
1450+
mkdir -p docs/_build/html/_static/websocket/conformance/without-nvx
1451+
mkdir -p docs/_build/html/_static/flatbuffers
14381452

14391453
# Copy conformance reports (with-nvx)
14401454
if [ -d "${DOWNLOAD_DIR}/with-nvx" ]; then
14411455
echo "==> Copying conformance reports (with NVX)..."
1442-
cp -r "${DOWNLOAD_DIR}/with-nvx"/* docs/_static/websocket/conformance/with-nvx/ 2>/dev/null || true
1443-
FILE_COUNT=$(find docs/_static/websocket/conformance/with-nvx -type f | wc -l)
1444-
echo "✅ Copied ${FILE_COUNT} files to docs/_static/websocket/conformance/with-nvx/"
1456+
cp -r "${DOWNLOAD_DIR}/with-nvx"/* docs/_build/html/_static/websocket/conformance/with-nvx/ 2>/dev/null || true
1457+
FILE_COUNT=$(find docs/_build/html/_static/websocket/conformance/with-nvx -type f | wc -l)
1458+
echo "✅ Copied ${FILE_COUNT} files to docs/_build/html/_static/websocket/conformance/with-nvx/"
14451459
else
14461460
echo "⚠️ No with-nvx conformance reports found in ${DOWNLOAD_DIR}"
14471461
fi
14481462

14491463
# Copy conformance reports (without-nvx)
14501464
if [ -d "${DOWNLOAD_DIR}/without-nvx" ]; then
14511465
echo "==> Copying conformance reports (without NVX)..."
1452-
cp -r "${DOWNLOAD_DIR}/without-nvx"/* docs/_static/websocket/conformance/without-nvx/ 2>/dev/null || true
1453-
FILE_COUNT=$(find docs/_static/websocket/conformance/without-nvx -type f | wc -l)
1454-
echo "✅ Copied ${FILE_COUNT} files to docs/_static/websocket/conformance/without-nvx/"
1466+
cp -r "${DOWNLOAD_DIR}/without-nvx"/* docs/_build/html/_static/websocket/conformance/without-nvx/ 2>/dev/null || true
1467+
FILE_COUNT=$(find docs/_build/html/_static/websocket/conformance/without-nvx -type f | wc -l)
1468+
echo "✅ Copied ${FILE_COUNT} files to docs/_build/html/_static/websocket/conformance/without-nvx/"
14551469
else
14561470
echo "⚠️ No without-nvx conformance reports found in ${DOWNLOAD_DIR}"
14571471
fi
@@ -1460,8 +1474,8 @@ docs-integrate-github-release release_tag="":
14601474
echo "==> Copying FlatBuffers source schemas (.fbs)..."
14611475
FBS_COUNT=$(find "${DOWNLOAD_DIR}" -maxdepth 1 -name "*.fbs" -type f 2>/dev/null | wc -l)
14621476
if [ "${FBS_COUNT}" -gt 0 ]; then
1463-
cp "${DOWNLOAD_DIR}"/*.fbs docs/_static/flatbuffers/ 2>/dev/null || true
1464-
echo "✅ Copied ${FBS_COUNT} .fbs files to docs/_static/flatbuffers/"
1477+
cp "${DOWNLOAD_DIR}"/*.fbs docs/_build/html/_static/flatbuffers/ 2>/dev/null || true
1478+
echo "✅ Copied ${FBS_COUNT} .fbs files to docs/_build/html/_static/flatbuffers/"
14651479
else
14661480
echo "⚠️ No .fbs files found in ${DOWNLOAD_DIR}"
14671481
fi
@@ -1470,31 +1484,30 @@ docs-integrate-github-release release_tag="":
14701484
echo "==> Copying FlatBuffers binary schemas (.bfbs)..."
14711485
BFBS_COUNT=$(find "${DOWNLOAD_DIR}" -maxdepth 1 -name "*.bfbs" -type f 2>/dev/null | wc -l)
14721486
if [ "${BFBS_COUNT}" -gt 0 ]; then
1473-
cp "${DOWNLOAD_DIR}"/*.bfbs docs/_static/flatbuffers/ 2>/dev/null || true
1474-
echo "✅ Copied ${BFBS_COUNT} .bfbs files to docs/_static/flatbuffers/"
1487+
cp "${DOWNLOAD_DIR}"/*.bfbs docs/_build/html/_static/flatbuffers/ 2>/dev/null || true
1488+
echo "✅ Copied ${BFBS_COUNT} .bfbs files to docs/_build/html/_static/flatbuffers/"
14751489
else
14761490
echo "⚠️ No .bfbs files found in ${DOWNLOAD_DIR}"
14771491
fi
14781492

14791493
# Also check for schema/ and wamp/ subdirectories (alternative structure)
14801494
if [ -d "${DOWNLOAD_DIR}/schema" ] || [ -d "${DOWNLOAD_DIR}/wamp" ]; then
14811495
echo "==> Copying FlatBuffers schema directories..."
1482-
[ -d "${DOWNLOAD_DIR}/schema" ] && cp -r "${DOWNLOAD_DIR}/schema" docs/_static/flatbuffers/ 2>/dev/null || true
1483-
[ -d "${DOWNLOAD_DIR}/wamp" ] && cp -r "${DOWNLOAD_DIR}/wamp" docs/_static/flatbuffers/ 2>/dev/null || true
1496+
[ -d "${DOWNLOAD_DIR}/schema" ] && cp -r "${DOWNLOAD_DIR}/schema" docs/_build/html/_static/flatbuffers/ 2>/dev/null || true
1497+
[ -d "${DOWNLOAD_DIR}/wamp" ] && cp -r "${DOWNLOAD_DIR}/wamp" docs/_build/html/_static/flatbuffers/ 2>/dev/null || true
14841498
echo "✅ Copied schema directories"
14851499
fi
14861500

14871501
echo ""
14881502
echo "════════════════════════════════════════════════════════════"
1489-
echo "✅ GitHub release artifacts integrated into docs build"
1503+
echo "✅ GitHub release artifacts integrated into built documentation"
14901504
echo "════════════════════════════════════════════════════════════"
14911505
echo ""
14921506
echo "Integrated artifacts from: ${RELEASE_TAG}"
1493-
echo "Target location: docs/_static/"
1507+
echo "Target location: docs/_build/html/_static/"
14941508
echo ""
14951509
echo "Next steps:"
1496-
echo " 1. Build documentation: just docs"
1497-
echo " 2. View documentation: just docs-view"
1498-
echo " 3. Check conformance reports at: docs/_build/html/websocket/conformance.html"
1499-
echo " 4. Check FlatBuffers schemas at: docs/_build/html/wamp/serialization.html"
1510+
echo " 1. View documentation: just docs-view"
1511+
echo " 2. Check conformance reports at: http://localhost:8000/websocket/conformance.html"
1512+
echo " 3. Check FlatBuffers schemas at: http://localhost:8000/wamp/serialization.html"
15001513
echo ""

0 commit comments

Comments
 (0)