[llvm] [docs] Release manpages (PR #201376)
via llvm-commits
llvm-commits at lists.llvm.org
Wed Jun 3 08:00:45 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-github-workflow
Author: Konrad Kleine (kwk)
<details>
<summary>Changes</summary>
This adds the possibility to generate manpages from the `llvm/utils/release/build-docs.sh` script. Furthermore this adds a new github workflow to release those manpages.
This was done to prevent problems when myst-parser will be used to process all documentation in LLVM. See https://discourse.llvm.org/t/rfc-make-myst-markdown-the-llvm-docs-format-rip-rest/90840/26?u=kwk
Additionally the `build-docs.sh` script now determines the release from the source directory if no release was given. Otherwise the generated tarballs would be missing the release entirely. To make it clear that something was generated from any git directory, a short git revision will be attached to the release (e.g. `23.0.0-gc823de88d51f58`).
---
Full diff: https://github.com/llvm/llvm-project/pull/201376.diff
4 Files Affected:
- (modified) .github/workflows/release-documentation.yml (+1-1)
- (modified) .github/workflows/release-doxygen.yml (+1-1)
- (added) .github/workflows/release-manpages.yml (+121)
- (modified) llvm/utils/release/build-docs.sh (+42-7)
``````````diff
diff --git a/.github/workflows/release-documentation.yml b/.github/workflows/release-documentation.yml
index f844b5a71103c..af3836e2982d1 100644
--- a/.github/workflows/release-documentation.yml
+++ b/.github/workflows/release-documentation.yml
@@ -72,7 +72,7 @@ jobs:
GITHUB_TOKEN: ${{ github.token }}
INPUTS_RELEASE_VERSION: ${{ inputs.release-version }}
run: |
- ./llvm/utils/release/build-docs.sh -release "$INPUTS_RELEASE_VERSION" -no-doxygen
+ ./llvm/utils/release/build-docs.sh -release "$INPUTS_RELEASE_VERSION" -no-doxygen -no-manpages
- name: Create Release Notes Artifact
uses: actions/upload-artifact at 043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
diff --git a/.github/workflows/release-doxygen.yml b/.github/workflows/release-doxygen.yml
index 548e17adbd023..9464447712bdd 100644
--- a/.github/workflows/release-doxygen.yml
+++ b/.github/workflows/release-doxygen.yml
@@ -104,7 +104,7 @@ jobs:
env:
RELEASE_VERSION: ${{ inputs.release-version }}
run: |
- ./llvm/utils/release/build-docs.sh -release "$RELEASE_VERSION" -no-sphinx
+ ./llvm/utils/release/build-docs.sh -release "$RELEASE_VERSION" -no-sphinx -no-manpages
- id: app-token
uses: actions/create-github-app-token at 1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
diff --git a/.github/workflows/release-manpages.yml b/.github/workflows/release-manpages.yml
new file mode 100644
index 0000000000000..f2aadcb75761b
--- /dev/null
+++ b/.github/workflows/release-manpages.yml
@@ -0,0 +1,121 @@
+name: Release Manpages
+
+permissions:
+ contents: read
+
+on:
+ workflow_dispatch:
+ inputs:
+ release-version:
+ description: 'Release Version'
+ required: true
+ type: string
+ upload:
+ description: 'Upload documentation'
+ required: false
+ type: boolean
+
+ workflow_call:
+ inputs:
+ release-version:
+ description: 'Release Version'
+ required: true
+ type: string
+ upload:
+ description: 'Upload documentation'
+ required: false
+ type: boolean
+ secrets:
+ LLVM_TOKEN_GENERATOR_CLIENT_ID:
+ description: "Client ID for our GitHub App we use for generating access tokens."
+ required: true
+ LLVM_TOKEN_GENERATOR_PRIVATE_KEY:
+ description: "Private key for our GitHub App we use for generating access tokens."
+ required: true
+
+jobs:
+ # This job checks permissions and validates inputs to prevent potential
+ # malicious actions. Since the release-manpages job has contents: write
+ # permissions we need to be extra careful about who can run the job and
+ # what inputs can be provided.
+ release-manpages-validate-input:
+ name: Release Manpage Validate Input
+ runs-on: ubuntu-24.04
+ environment:
+ name: release
+ deployment: false
+ permissions:
+ contents: read
+ steps:
+ - uses: actions/checkout at de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+ sparse-checkout: |
+ .github/workflows/
+
+ - name: Check Permissions
+ uses: ./.github/workflows/require-team-membership
+ with:
+ team-slug: llvm-release-managers
+ LLVM_TOKEN_GENERATOR_CLIENT_ID: ${{ secrets.LLVM_TOKEN_GENERATOR_CLIENT_ID }}
+ LLVM_TOKEN_GENERATOR_PRIVATE_KEY: ${{ secrets.LLVM_TOKEN_GENERATOR_PRIVATE_KEY }}
+
+ - name: Validate Input
+ uses: ./.github/workflows/validate-release-version
+ with:
+ release-version: ${{ inputs.release-version }}
+
+ release-manpages:
+ name: Build and Upload Release Manpages
+ runs-on: ubuntu-24.04
+ environment:
+ name: release
+ deployment: false
+ permissions:
+ contents: write
+ needs:
+ - release-manpages-validate-input
+ env:
+ upload: ${{ inputs.upload && !contains(inputs.release-version, 'rc') }}
+ steps:
+ - name: Checkout LLVM
+ uses: actions/checkout at de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+
+ - name: Setup Python env
+ uses: actions/setup-python at a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+ with:
+ cache: 'pip'
+ cache-dependency-path: './llvm/docs/requirements.txt'
+
+ - name: Install Dependencies
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y \
+ python3-github \
+ ninja-build \
+ pip3 install --require-hashes --user -r ./llvm/docs/requirements.txt
+
+ - name: Build Manpages
+ env:
+ RELEASE_VERSION: ${{ inputs.release-version }}
+ run: |
+ ./llvm/utils/release/build-docs.sh -release "$RELEASE_VERSION" -no-sphinx -no-doxygen
+
+ - id: app-token
+ uses: actions/create-github-app-token at 1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+ with:
+ app-id: ${{ secrets.LLVM_TOKEN_GENERATOR_CLIENT_ID }}
+ private-key: ${{ secrets.LLVM_TOKEN_GENERATOR_PRIVATE_KEY }}
+ owner: ${{ github.repository_owner }}
+ permission-members: read
+
+ - name: Upload Manpages
+ if: env.upload
+ env:
+ GITHUB_TOKEN: ${{ github.token }}
+ USER_TOKEN: ${{ steps.app-token.outputs.token }}
+ RELEASE_VERSION: ${{ inputs.release-version }}
+ run: |
+ ./llvm/utils/release/github-upload-release.py --token "$GITHUB_TOKEN" --release "$RELEASE_VERSION" --user "$GITHUB_ACTOR" --user-token "$USER_TOKEN" upload --files ./llvm_manpages-*.tar.xz
diff --git a/llvm/utils/release/build-docs.sh b/llvm/utils/release/build-docs.sh
index bc32f209419e4..5aca998c74c4a 100755
--- a/llvm/utils/release/build-docs.sh
+++ b/llvm/utils/release/build-docs.sh
@@ -36,6 +36,7 @@ usage() {
echo " (optional) default: $srcdir"
echo " -no-doxygen Don't build Doxygen docs"
echo " -no-sphinx Don't build Spinx docs"
+ echo " -no-manpages Don't build manpages"
}
package_doxygen() {
@@ -65,6 +66,9 @@ while [ $# -gt 0 ]; do
-no-sphinx )
no_sphinx="yes"
;;
+ -no-manpages )
+ no_manpages="yes"
+ ;;
* )
echo "unknown option: $1"
usage
@@ -97,11 +101,19 @@ if [ -n "$release" ]; then
srcdir="./llvm-project/llvm"
fi
-if [ "$no_doxygen" == "yes" ] && [ "$no_sphinx" == "yes" ]; then
- echo "You can't specify both -no-doxygen and -no-sphinx, we have nothing to build then!"
+if [ "$no_doxygen" == "yes" ] && [ "$no_sphinx" == "yes" ] && [ "$no_manpages" == "yes" ]; then
+ echo "You can't specify -no-doxygen, -no-sphinx, and -no-manpages, we have nothing to build then!"
exit 1
fi
+# Try to determine the release from the current git directory if none is given
+# and format it like this: 23.0.0-gc823de88d51f58
+if [ -z "$release" ]; then
+ release=$(git -C $srcdir show HEAD:cmake/Modules/LLVMVersion.cmake | grep -ioP 'set\(\s*LLVM_VERSION_(MAJOR|MINOR|PATCH)\s\K[0-9]+' | paste -sd '.')
+ git_rev=$(git rev-parse HEAD)
+ release="$release-g${git_rev:0:14}"
+fi
+
if [ "$no_sphinx" != "yes" ]; then
echo "Sphinx: enabled"
sphinx_targets="docs-clang-html docs-clang-tools-html docs-flang-html docs-lld-html docs-llvm-html docs-polly-html"
@@ -110,6 +122,16 @@ else
echo "Sphinx: disabled"
fi
+if [ "$no_manpages" != "yes" ]; then
+ echo "Manpages: enabled"
+ manpage_targets="docs-clang-man docs-clang-tools-man docs-dsymutil-man docs-flang-man docs-lldb-man docs-llvm-dwarfdump-man docs-llvm-man docs-polly-man"
+ manpage_flag=" -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF -DSPHINX_OUTPUT_MAN:BOOL=ON"
+ extra_manpage_projects=";lldb;mlir;bolt"
+ extra_manpage_runtimes=";compiler-rt;openmp;"
+else
+ echo "Manpages: disabled"
+fi
+
if [ "$no_doxygen" != "yes" ]; then
echo "Doxygen: enabled"
doxygen_targets="$docs_target doxygen-clang doxygen-clang-tools doxygen-flang doxygen-llvm doxygen-mlir doxygen-polly"
@@ -118,22 +140,35 @@ else
echo "Doxygen: disabled"
fi
+# This is just to ensure we're using the right compiler
+# When running this locally, the script otherwise might
+# prefer GCC.
+export CC=clang
+export CXX=clang++
+
cmake -G Ninja $srcdir -B $builddir \
- -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra;lld;polly;flang" \
+ -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra;lld;polly;flang${extra_manpage_projects}" \
-DCMAKE_BUILD_TYPE=Release \
-DLLVM_BUILD_DOCS=ON \
$sphinx_flag \
- $doxygen_flag
+ $doxygen_flag \
+ $manpage_flag
-ninja -C $builddir $sphinx_targets $doxygen_targets
+ninja -C $builddir $sphinx_targets $doxygen_targets $manpage_targets
cmake -G Ninja $srcdir/../runtimes -B $builddir/runtimes-doc \
- -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \
+ -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind;${extra_manpage_runtimes}" \
-DLLVM_ENABLE_SPHINX=ON \
-DSPHINX_WARNINGS_AS_ERRORS=OFF
ninja -C $builddir/runtimes-doc \
- docs-libcxx-html \
+ docs-libcxx-html
+
+if [ "$no_manpage" != "yes" ]; then
+ output="llvm_manpages-$release"
+ mv $builddir/docs/man $output
+ tar -cJf $output.tar.xz $output
+fi
if [ "$no_doxygen" != "yes" ]; then
package_doxygen llvm .
``````````
</details>
https://github.com/llvm/llvm-project/pull/201376
More information about the llvm-commits
mailing list