建文檔站，1 條命令生成發(fā)布日志)
AMD ROCm 官方文檔倉庫完全指南5 分鐘本地構(gòu)建文檔站1 條命令生成發(fā)布日志【免費下載鏈接】legacy-rocm-buildAMD ROCm? Software - GitHub Home項目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build想搞清楚官方 ROCm 文檔是怎么做出來的還是想親手改一改那張兼容性矩陣這個倉庫就是 AMD ROCm 官方文檔的源頭完整的文檔源碼、Sphinx 構(gòu)建流水線、發(fā)布 changelog 自動化工具全都在里面。這篇文章帶你從 clone 到本地出頁再一路鉆到工具鏈內(nèi)部。它到底干什么ROCm 文檔的中央廚房先說清楚這個倉庫不是ROCm 軟件棧本身。驅(qū)動、rocBLAS、HIP 這些組件都住在各自的倉庫里。這里放的是另一樣?xùn)|西文檔源碼全集安裝指南、兼容性矩陣、組件清單、GPU 架構(gòu)參考目錄都在docs/下構(gòu)建流水線根目錄CMakeLists.txt Sphinx把docs/變成你在線上看到的網(wǎng)站發(fā)布工具鏈tools/autotag/管 changelog 生成tools/precision-support/管精度支持審計一句話你在瀏覽器里讀到的 ROCm 官方文檔就是從這堆文件里印出來的。坦白講一個背景README 頂部標(biāo)注了本倉庫將逐步讓位于 TheRock 項目。但這不妨礙它的價值——想看懂 ROCm 文檔是怎么生產(chǎn)出來的這里是目前最完整的一份活樣本。runfile 安裝器主菜單截圖這類帶圖安裝教程全部由本倉庫docs/install/目錄排版產(chǎn)出?？赐昙业紫乱徊疆?dāng)然是跑起來。5 分鐘跑通本地兩條命令起出文檔站這一節(jié)回答一個問題從零 clone 到瀏覽器里看到渲染結(jié)果要多久不急的話走官方 CMake 流水線# 1. 拉取源碼 git clone https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build cd legacy-rocm-build # 2. 配置。BUILD_DOCS 默認(rèn)開啟 # cmake/Modules/Dependencies.cmake 在找不到 rocm-cmake 時會自動 FetchContent 拉取 cmake -B build # 3. 構(gòu)建文檔產(chǎn)物為 html 并安裝到 doxygen 目錄 cmake --build build趕時間的話docs/contribute/building.md里記著一條更直接的捷徑venv sphinx 兩步走# 建干凈虛擬環(huán)境裝文檔構(gòu)建依賴sphinx、主題、擴展一份 requirements 全包 python3 -mvenv .venv .venv/bin/python -m pip install -r docs/sphinx/requirements.txt # 構(gòu)建 html。-T 打印完整報錯-E 不復(fù)用舊緩存 .venv/bin/python -m sphinx -T -E -b html -d _build/doctrees \ -D languageen docs _build/html完事用瀏覽器打開_build/html/index.html從docs/目錄內(nèi)運行的話產(chǎn)物在docs/_build/html/。頁面能打開、左側(cè)導(dǎo)航樹正常冒煙測試就算過了。頁是出來了那頁面里的每一塊內(nèi)容源碼到底存在哪3 分鐘目錄巡禮文檔源碼住在哪里對著目錄看五分鐘建立空間感docs/install/、docs/reference/、docs/components/、docs/compatibility/四大文檔板塊一板塊一個目錄線上站點的左側(cè)導(dǎo)航就來自docs/sphinx/_toc.yml.indocs/data/所有驅(qū)動頁面的數(shù)據(jù)文件components.yaml、參考用 CSV 全在這docs/extension/rocm_docs_custom/一組自研 Sphinx 擴展是這套文檔的秘密武器下一節(jié)細說tools/autotag/與tools/precision-support/發(fā)布期工具文章后半段的兩位主角cmake/Modules/ 根CMakeLists.txt構(gòu)建入口文檔內(nèi)容本身覆蓋得有多深看參考區(qū)就知道。比如 GPU 架構(gòu)板塊從 MI100 到 MI350 的微架構(gòu)、性能計數(shù)器文檔一卡一檔參考文檔中使用的 MI300 節(jié)點架構(gòu)圖8 張 GPU 經(jīng) Infinity Fabric 互聯(lián)。文檔站渲染的正是這類硬件深度內(nèi)容。數(shù)據(jù)放哪、圖片放哪都清楚了最后一個問題表格類內(nèi)容為什么改一次、處處生效數(shù)據(jù)驅(qū)動一張兼容性表格是怎么上頁的把文檔站想象成印刷廠這套架構(gòu)的答案就出來了內(nèi)容是預(yù)制字模不是手寫稿。鏈路三步走docs/data/里的 YAML / CSV 是唯一數(shù)據(jù)源。components.yaml管組件清單reference/下的 CSV 管原子操作支持、精度支持這類硬表格docs/extension/rocm_docs_custom/下的擴展在構(gòu)建時做排版csv_list_to_table把 CSV 直接變表格merge_components把多份 YAML 合并成組件總表version_ref負責(zé)把當(dāng)前版本號填進正文selector做頁面上的選項切換Sphinx 出 HTML。改數(shù)據(jù)不用碰一個字的文章正文這就是為什么兼容性矩陣、組件表、GPU 表能在幾十個頁面間保持一致——它們共用同一份紙。計算單元CU結(jié)構(gòu)圖調(diào)度器、SIMD、LDS 與寄存器文件的層次關(guān)系。參考區(qū)這類硬件圖解就是數(shù)據(jù)加模板批量印出來的。數(shù)據(jù)鏈路通了時間線也得通——這活兒歸 changelog。一條命令生成發(fā)布日志autotag 流水線tools/autotag/是發(fā)布季的記賬員。原理拆開看很簡單人只維護模板tools/autotag/templates/下按變更類型分四個目錄highlights、known_issues、resolved_issues、support每版一個 md 文件腳本干活tag_script.py按發(fā)布分支遍歷各組件倉庫的 changelog拼裝成頂層CHANGELOG.md命令倉庫 README 里寫得很明白export GITHUB_ACCESS_TOKENyour_token_here cd tools/autotag # 生成從 5.0.0 到 6.4.0含的完整 changelog python3 tag_script.py -t $GITHUB_ACCESS_TOKEN --no-release --no-pulls \ --starting-version5.0.0 \ --compile_file ../../CHANGELOG.md \ --branch release/rocm-rel-6.4 6.4.0兩條鐵律踩一條就返工只改模板別手改CHANGELOG.md。腳本每次全量重生成手寫內(nèi)容會被直接覆蓋永遠帶 token。裸跑會被 GitHub 更嚴(yán)的限流卡住腳本自己都提示not advisedchangelog 記的是改了什么還有一個更細的問題各庫到底支持哪些數(shù)據(jù)類型這就是質(zhì)檢站的活。跨版本精度審計質(zhì)檢站tools/precision-support/干的是逐版本對賬。鏈路是precision_fetch.py把各庫的源文件和 YAML 快照拉到/tmp/manifest_diff.py負責(zé)差異比對README 里還配了/precision-check PREV CURR一鍵審計全量掃和按 SHA 過濾的增量掃各有一檔。審計的落點是一個文件docs/data/reference/precision-support/precision-support-meta.yaml——站點上精度支持表的數(shù)據(jù)源。至此工具鏈閉環(huán)了changelog 是記賬員審計是質(zhì)檢員一起守發(fā)布質(zhì)量。排坑速查四道高頻故障一張表癥狀30 秒自查大概率缺了什么sphinx 報缺模塊.venv/bin/python -m pip install -r docs/sphinx/requirements.txtvenv 建了依賴沒裝CMake 找不到 ROCM默認(rèn)會 FetchContent 自動拉 rocm-cmake網(wǎng)絡(luò)不通可手動傳-DROCM_PATH路徑指向已裝位置changelog 內(nèi)容不對核對tools/autotag/templates/下的模板手改了生成產(chǎn)物被腳本覆蓋GitHub 接口限流帶-t $GITHUB_ACCESS_TOKEN重跑沒帶 token外加一條改過 Doxygen 注釋的話兩次構(gòu)建之間刪掉舊的 doxygen 緩存目錄別拿臟緩存嚇自己。下一步去哪四件馬上能做的事文檔站是 ROCm 平臺的櫥窗而櫥窗后面的生產(chǎn)線才是更值錢的資產(chǎn)?？炊@條線你就不只是讀者是能拆掉櫥窗重搭一間的施工隊了。把 CMake 官方流水線完整跑一遍對照線上文檔看產(chǎn)物差在哪挑docs/data/下一個 CSV改一個格子重建親眼看兼容性矩陣更新——數(shù)據(jù)驅(qū)動的感覺一下就來了讀一遍docs/extension/rocm_docs_custom/csv_list_to_table/的源碼它是自研 Sphinx 擴展最簡潔的范本把tools/autotag/和tools/precision-support/的 README 讀透用只讀 token 跑一次精度抓取體會發(fā)布季的工具鏈機器已經(jīng)熱好了剩下的輪子在你手上?！久赓M下載鏈接】legacy-rocm-buildAMD ROCm? Software - GitHub Home項目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 AMD ROCm 官方文檔倉庫完全指南：5 分鐘本地構(gòu)建文檔站，1 條命令生成發(fā)布日志
AMD ROCm 官方文檔倉庫完全指南5 分鐘本地構(gòu)建文檔站1 條命令生成發(fā)布日志【免費下載鏈接】legacy-rocm-buildAMD ROCm? Software - GitHub Home項目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build想搞清楚官方 ROCm 文檔是怎么做出來的還是想親手改一改那張兼容性矩陣這個倉庫就是 AMD ROCm 官方文檔的源頭完整的文檔源碼、Sphinx 構(gòu)建流水線、發(fā)布 changelog 自動化工具全都在里面。這篇文章帶你從 clone 到本地出頁再一路鉆到工具鏈內(nèi)部。它到底干什么ROCm 文檔的中央廚房先說清楚這個倉庫不是ROCm 軟件棧本身。驅(qū)動、rocBLAS、HIP 這些組件都住在各自的倉庫里。這里放的是另一樣?xùn)|西文檔源碼全集安裝指南、兼容性矩陣、組件清單、GPU 架構(gòu)參考目錄都在docs/下構(gòu)建流水線根目錄CMakeLists.txt Sphinx把docs/變成你在線上看到的網(wǎng)站發(fā)布工具鏈tools/autotag/管 changelog 生成tools/precision-support/管精度支持審計一句話你在瀏覽器里讀到的 ROCm 官方文檔就是從這堆文件里印出來的。坦白講一個背景README 頂部標(biāo)注了本倉庫將逐步讓位于 TheRock 項目。但這不妨礙它的價值——想看懂 ROCm 文檔是怎么生產(chǎn)出來的這里是目前最完整的一份活樣本。runfile 安裝器主菜單截圖這類帶圖安裝教程全部由本倉庫docs/install/目錄排版產(chǎn)出?？赐昙业紫乱徊疆?dāng)然是跑起來。5 分鐘跑通本地兩條命令起出文檔站這一節(jié)回答一個問題從零 clone 到瀏覽器里看到渲染結(jié)果要多久不急的話走官方 CMake 流水線# 1. 拉取源碼 git clone https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build cd legacy-rocm-build # 2. 配置。BUILD_DOCS 默認(rèn)開啟 # cmake/Modules/Dependencies.cmake 在找不到 rocm-cmake 時會自動 FetchContent 拉取 cmake -B build # 3. 構(gòu)建文檔產(chǎn)物為 html 并安裝到 doxygen 目錄 cmake --build build趕時間的話docs/contribute/building.md里記著一條更直接的捷徑venv sphinx 兩步走# 建干凈虛擬環(huán)境裝文檔構(gòu)建依賴sphinx、主題、擴展一份 requirements 全包 python3 -mvenv .venv .venv/bin/python -m pip install -r docs/sphinx/requirements.txt # 構(gòu)建 html。-T 打印完整報錯-E 不復(fù)用舊緩存 .venv/bin/python -m sphinx -T -E -b html -d _build/doctrees \ -D languageen docs _build/html完事用瀏覽器打開_build/html/index.html從docs/目錄內(nèi)運行的話產(chǎn)物在docs/_build/html/。頁面能打開、左側(cè)導(dǎo)航樹正常冒煙測試就算過了。頁是出來了那頁面里的每一塊內(nèi)容源碼到底存在哪3 分鐘目錄巡禮文檔源碼住在哪里對著目錄看五分鐘建立空間感docs/install/、docs/reference/、docs/components/、docs/compatibility/四大文檔板塊一板塊一個目錄線上站點的左側(cè)導(dǎo)航就來自docs/sphinx/_toc.yml.indocs/data/所有驅(qū)動頁面的數(shù)據(jù)文件components.yaml、參考用 CSV 全在這docs/extension/rocm_docs_custom/一組自研 Sphinx 擴展是這套文檔的秘密武器下一節(jié)細說tools/autotag/與tools/precision-support/發(fā)布期工具文章后半段的兩位主角cmake/Modules/ 根CMakeLists.txt構(gòu)建入口文檔內(nèi)容本身覆蓋得有多深看參考區(qū)就知道。比如 GPU 架構(gòu)板塊從 MI100 到 MI350 的微架構(gòu)、性能計數(shù)器文檔一卡一檔參考文檔中使用的 MI300 節(jié)點架構(gòu)圖8 張 GPU 經(jīng) Infinity Fabric 互聯(lián)。文檔站渲染的正是這類硬件深度內(nèi)容。數(shù)據(jù)放哪、圖片放哪都清楚了最后一個問題表格類內(nèi)容為什么改一次、處處生效數(shù)據(jù)驅(qū)動一張兼容性表格是怎么上頁的把文檔站想象成印刷廠這套架構(gòu)的答案就出來了內(nèi)容是預(yù)制字模不是手寫稿。鏈路三步走docs/data/里的 YAML / CSV 是唯一數(shù)據(jù)源。components.yaml管組件清單reference/下的 CSV 管原子操作支持、精度支持這類硬表格docs/extension/rocm_docs_custom/下的擴展在構(gòu)建時做排版csv_list_to_table把 CSV 直接變表格merge_components把多份 YAML 合并成組件總表version_ref負責(zé)把當(dāng)前版本號填進正文selector做頁面上的選項切換Sphinx 出 HTML。改數(shù)據(jù)不用碰一個字的文章正文這就是為什么兼容性矩陣、組件表、GPU 表能在幾十個頁面間保持一致——它們共用同一份紙。計算單元CU結(jié)構(gòu)圖調(diào)度器、SIMD、LDS 與寄存器文件的層次關(guān)系。參考區(qū)這類硬件圖解就是數(shù)據(jù)加模板批量印出來的。數(shù)據(jù)鏈路通了時間線也得通——這活兒歸 changelog。一條命令生成發(fā)布日志autotag 流水線tools/autotag/是發(fā)布季的記賬員。原理拆開看很簡單人只維護模板tools/autotag/templates/下按變更類型分四個目錄highlights、known_issues、resolved_issues、support每版一個 md 文件腳本干活tag_script.py按發(fā)布分支遍歷各組件倉庫的 changelog拼裝成頂層CHANGELOG.md命令倉庫 README 里寫得很明白export GITHUB_ACCESS_TOKENyour_token_here cd tools/autotag # 生成從 5.0.0 到 6.4.0含的完整 changelog python3 tag_script.py -t $GITHUB_ACCESS_TOKEN --no-release --no-pulls \ --starting-version5.0.0 \ --compile_file ../../CHANGELOG.md \ --branch release/rocm-rel-6.4 6.4.0兩條鐵律踩一條就返工只改模板別手改CHANGELOG.md。腳本每次全量重生成手寫內(nèi)容會被直接覆蓋永遠帶 token。裸跑會被 GitHub 更嚴(yán)的限流卡住腳本自己都提示not advisedchangelog 記的是改了什么還有一個更細的問題各庫到底支持哪些數(shù)據(jù)類型這就是質(zhì)檢站的活。跨版本精度審計質(zhì)檢站tools/precision-support/干的是逐版本對賬。鏈路是precision_fetch.py把各庫的源文件和 YAML 快照拉到/tmp/manifest_diff.py負責(zé)差異比對README 里還配了/precision-check PREV CURR一鍵審計全量掃和按 SHA 過濾的增量掃各有一檔。審計的落點是一個文件docs/data/reference/precision-support/precision-support-meta.yaml——站點上精度支持表的數(shù)據(jù)源。至此工具鏈閉環(huán)了changelog 是記賬員審計是質(zhì)檢員一起守發(fā)布質(zhì)量。排坑速查四道高頻故障一張表癥狀30 秒自查大概率缺了什么sphinx 報缺模塊.venv/bin/python -m pip install -r docs/sphinx/requirements.txtvenv 建了依賴沒裝CMake 找不到 ROCM默認(rèn)會 FetchContent 自動拉 rocm-cmake網(wǎng)絡(luò)不通可手動傳-DROCM_PATH路徑指向已裝位置changelog 內(nèi)容不對核對tools/autotag/templates/下的模板手改了生成產(chǎn)物被腳本覆蓋GitHub 接口限流帶-t $GITHUB_ACCESS_TOKEN重跑沒帶 token外加一條改過 Doxygen 注釋的話兩次構(gòu)建之間刪掉舊的 doxygen 緩存目錄別拿臟緩存嚇自己。下一步去哪四件馬上能做的事文檔站是 ROCm 平臺的櫥窗而櫥窗后面的生產(chǎn)線才是更值錢的資產(chǎn)?？炊@條線你就不只是讀者是能拆掉櫥窗重搭一間的施工隊了。把 CMake 官方流水線完整跑一遍對照線上文檔看產(chǎn)物差在哪挑docs/data/下一個 CSV改一個格子重建親眼看兼容性矩陣更新——數(shù)據(jù)驅(qū)動的感覺一下就來了讀一遍docs/extension/rocm_docs_custom/csv_list_to_table/的源碼它是自研 Sphinx 擴展最簡潔的范本把tools/autotag/和tools/precision-support/的 README 讀透用只讀 token 跑一次精度抓取體會發(fā)布季的工具鏈機器已經(jīng)熱好了剩下的輪子在你手上?！久赓M下載鏈接】legacy-rocm-buildAMD ROCm? Software - GitHub Home項目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考