Skip to content

Commit c93fdc4

Browse files
parth-07parth-07
committed
Add support for generating multiversion documentation
This commit add supports for generating multiversion documentation. The new targets added that enable this functionality are: - `eld-docs-<release>` // <release> can be one of the releases such as // 22.x, and main. - `eld-docs-all-releases` // Builds all releases - `eld-docs-assemble` // Combines all the version documentation and // generates the version selector page. - `eld-docs-multiversion` // eld-docs-all-releases + eld-docs-assemble `eld-docs-<release>` creates the documentation by creating an eld worktree in ${BUILD_DIR}/tools/eld/docs/multiversion/_work/${release} with the requested release checked out. Please note that we cannot use the original source repository to generate documentations of different releases. In the generated docs: - the homepage ('/'), and '/main' will display the 'main' documentation. - '/22.x' and '/stable' will display the 'release/22.x' documentation. - '/versions.html' will display a basic documentation version selector menu. Signed-off-by: Parth Arora <partaror@qti.qualcomm.com>
1 parent e6316e6 commit c93fdc4

9 files changed

Lines changed: 734 additions & 6 deletions

File tree

‎.github/workflows/docs-multiversion.yaml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: Bulid multi-version docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths: ['docs/**', 'include/**']
7+
workflow_dispatch:
8+
pull_request:
9+
paths:
10+
- .github/workflows/docs-multiversion.yaml
11+
12+
jobs:
13+
build-docs-and-deploy:
14+
runs-on: ubuntu-latest
15+
concurrency:
16+
group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
17+
cancel-in-progress: true
18+
19+
steps:
20+
- name: Checkout llvm-project
21+
uses: actions/checkout@v4
22+
with:
23+
repository: llvm/llvm-project
24+
path: llvm-project
25+
ref: main
26+
27+
- name: Checkout eld
28+
uses: actions/checkout@v4
29+
with:
30+
path: llvm-project/llvm/tools/eld
31+
fetch-depth: 0
32+
33+
- name: Configure workflow environment
34+
uses: ./llvm-project/llvm/tools/eld/.github/workflows/ConfigureBuildWorkflowENV
35+
36+
- name: Set up Python
37+
uses: actions/setup-python@v4
38+
with:
39+
python-version: '3.11'
40+
41+
- name: Install dependencies
42+
run: |
43+
sudo apt-get update
44+
sudo apt-get install -y graphviz doxygen ninja-build
45+
pip install -r llvm-project/llvm/tools/eld/docs/userguide/requirements.txt
46+
47+
- name: Configure CMake
48+
run: |
49+
cmake -G Ninja -B build \
50+
-DCMAKE_BUILD_TYPE=Release \
51+
-DCMAKE_C_COMPILER=$(which clang) \
52+
-DCMAKE_CXX_COMPILER=$(which clang++) \
53+
-DLLVM_TARGETS_TO_BUILD="ARM;AArch64;RISCV;Hexagon" \
54+
-DLLVM_ENABLE_SPHINX=ON \
55+
llvm-project/llvm
56+
57+
- name: Build multi-version docs
58+
run: cmake --build build --target eld-docs-multiversion
59+
60+
- name: Checkout documentation branch
61+
uses: actions/checkout@v4
62+
with:
63+
ref: documentation
64+
path: docs-branch
65+
continue-on-error: true
66+
67+
- name: Preserve existing content (dashboard)
68+
run: |
69+
if [ -d dash ]; then
70+
cp -r dash build/tools/eld/docs/multiversion/site/main
71+
echo "Preserved dashboard from documentation branch"
72+
fi
73+
74+
- name: Deploy to documentation branch
75+
run: |
76+
SITE_DIR=$(pwd)/build/tools/eld/docs/multiversion/site
77+
cd llvm-project/llvm/tools/eld
78+
git config user.name 'github-actions'
79+
git config user.email 'github-actions@github.com'
80+
git checkout --orphan documentation-update
81+
git rm -rf .
82+
cp -r ${SITE_DIR}/. .
83+
git add .
84+
git commit -m "Update multi-version documentation"
85+
git push -f origin HEAD:refs/heads/documentation

‎.github/workflows/docs.yaml‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
name: Generate and Deploy Docs
22

33
on:
4-
push:
5-
branches:
6-
- main
7-
paths:
8-
- 'docs/**'
9-
- 'include/**'
4+
# push:
5+
# branches:
6+
# - main
7+
# paths:
8+
# - 'docs/**'
9+
# - 'include/**'
1010
workflow_dispatch: # Allows manual triggering
1111

1212
permissions:

‎cmake/modules/BuildMultiVersionDocs.cmake‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# BuildMultiVersionDocs.cmake
2+
#
3+
# Provides CMake targets for building multi-version ELD documentation.
4+
#
5+
# This module creates git worktrees for each configured version, builds
6+
# the eld-docs target for each, and assembles a combined site with a
7+
# landing page and version selector.
8+
#
9+
# Variables (user-configurable):
10+
# ELD_DOC_VERSIONS - List of "branch:label:display_name" specs
11+
# Example: "main:main:Main (dev);release/22.x:22.x:Release 22.x"
12+
# ELD_DOC_STABLE - Which version the "stable" symlink points to (default: 22.x)
13+
#
14+
# Targets created:
15+
# eld-docs-all-releases - Builds documentation for all configured versions
16+
# eld-docs-<name> - Builds documentation for a single version
17+
# eld-docs-assemble - Generates landing page and symlinks (depends on all versions)
18+
# eld-docs-multiversion - Convenience target: builds all + assembles
19+
#
20+
# Output:
21+
# ${CMAKE_BINARY_DIR}/tools/eld/docs/multiversion/site/
22+
# ├── index.html -> main/
23+
# ├── versions.json
24+
# ├── stable -> <ELD_DOC_STABLE>
25+
# ├── main/
26+
# └── 22.x/
27+
28+
function(eld_add_multiversion_doc_targets)
29+
if(NOT DEFINED ELD_SOURCE_DIR)
30+
message(FATAL_ERROR "ELD_SOURCE_DIR must be defined before calling eld_add_multiversion_doc_targets")
31+
endif()
32+
33+
find_package(Python3 REQUIRED COMPONENTS Interpreter)
34+
35+
set(ELD_DOC_VERSIONS
36+
"main:main:Main (dev)"
37+
"release/22.x:22.x:Release 22.x"
38+
CACHE STRING "Semicolon-separated list of 'branch:label:display_name' for multi-version docs")
39+
40+
set(ELD_DOC_STABLE "22.x"
41+
CACHE STRING "Version that 'stable' symlink points to")
42+
43+
set(ELD_MULTIVERSION_SCRIPTS_DIR "${ELD_SOURCE_DIR}/docs/multiversion")
44+
set(ELD_MULTIVERSION_WORK_DIR "${CMAKE_BINARY_DIR}/tools/eld/docs/multiversion")
45+
set(ELD_MULTIVERSION_SITE_DIR "${ELD_MULTIVERSION_WORK_DIR}/site")
46+
47+
# LLVM_SOURCE_DIR points to llvm/ subdirectory; parent is llvm-project root
48+
get_filename_component(ELD_LLVM_REPO_ROOT "${LLVM_SOURCE_DIR}/.." ABSOLUTE)
49+
if(NOT DEFINED LLVM_SOURCE_DIR OR NOT EXISTS "${ELD_LLVM_REPO_ROOT}/llvm/CMakeLists.txt")
50+
message(WARNING "LLVM_SOURCE_DIR not set or invalid")
51+
message(WARNING "Multi-version docs target will not be available")
52+
return()
53+
endif()
54+
55+
set(version_targets "")
56+
57+
foreach(version_spec IN LISTS ELD_DOC_VERSIONS)
58+
# Parse "branch:label" (display_name is handled by Python)
59+
string(REPLACE ":" ";" parts "${version_spec}")
60+
list(LENGTH parts num_parts)
61+
62+
if(num_parts LESS 2)
63+
message(WARNING "Invalid version spec (need at least branch:label): ${version_spec}")
64+
continue()
65+
endif()
66+
67+
list(GET parts 0 branch)
68+
list(GET parts 1 label)
69+
70+
# Create target for this version
71+
# Each version gets its own work directory to allow parallel builds
72+
set(target_name "eld-docs-${label}")
73+
set(version_work_dir "${ELD_MULTIVERSION_WORK_DIR}/_work/${label}")
74+
75+
add_custom_target(${target_name}
76+
COMMAND ${Python3_EXECUTABLE}
77+
"${ELD_MULTIVERSION_SCRIPTS_DIR}/build_docs.py"
78+
--branch "${branch}"
79+
--eld-repo "${ELD_SOURCE_DIR}"
80+
--llvm-repo "${ELD_LLVM_REPO_ROOT}"
81+
--work-dir "${version_work_dir}"
82+
--output-dir "${ELD_MULTIVERSION_SITE_DIR}/${label}"
83+
WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
84+
COMMENT "Building ELD docs: ${branch} -> ${label}"
85+
USES_TERMINAL
86+
VERBATIM
87+
)
88+
89+
list(APPEND version_targets ${target_name})
90+
endforeach()
91+
92+
# Main target that builds all versions
93+
add_custom_target(eld-docs-all-releases
94+
DEPENDS ${version_targets}
95+
COMMENT "Building all ELD documentation versions"
96+
)
97+
98+
add_custom_target(eld-docs-assemble
99+
DEPENDS eld-docs-all-releases
100+
COMMAND ${Python3_EXECUTABLE}
101+
"${ELD_MULTIVERSION_SCRIPTS_DIR}/assemble_site.py"
102+
--site-dir "${ELD_MULTIVERSION_SITE_DIR}"
103+
--versions-spec "${ELD_DOC_VERSIONS}"
104+
--stable "${ELD_DOC_STABLE}"
105+
WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
106+
COMMENT "Assembling multi-version documentation site"
107+
USES_TERMINAL
108+
VERBATIM
109+
)
110+
111+
# Convenience target that does everything
112+
add_custom_target(eld-docs-multiversion
113+
DEPENDS eld-docs-assemble
114+
COMMENT "Multi-version documentation complete: ${ELD_MULTIVERSION_SITE_DIR}"
115+
)
116+
117+
message(STATUS "Multi-version docs target: eld-docs-all-releases")
118+
message(STATUS " Versions: ${ELD_DOC_VERSIONS}")
119+
message(STATUS " Stable: ${ELD_DOC_STABLE}")
120+
message(STATUS " Output: ${ELD_MULTIVERSION_SITE_DIR}")
121+
122+
endfunction()

‎docs/CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
add_subdirectory(design)
22
add_subdirectory(userguide)
3+
add_subdirectory(multiversion)

‎docs/multiversion/CMakeLists.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
if(LLVM_ENABLE_SPHINX)
2+
include(BuildMultiVersionDocs)
3+
eld_add_multiversion_doc_targets()
4+
endif()

0 commit comments

Comments
 (0)