utils/release: Add script for building release documentation

[hans]

llvm/utils/release/build-docs.sh

21

I don't know if the script needs to comment on whether docs need to be built for -final releases or others.

(I also think it's useful to have them for release candidates, so people can get an idea of what the current state of the docs are.)

61

This should be relative to the script's dir, not the cwd. Is there some way to figure this out in bash?

70

This assumes srcdir is a git checkout. One could imagine someone wanting to build the docs after extracting the llvm-project tarball for example.

I think the script should either be able to build against any src dir, or it should take a git revision/tag and grab the sources itself.

In the script I used, it does the latter, using

curl -L https://github.com/llvm/llvm-project/archive/$GIT_REF.tar.gz | tar --strip-components=1 -xzf -

84

In my script I had -DLLVM_BUILD_DOCS=ON
I see that both exist in the cmake files.. not sure what the difference is.

101

In my script I had to move the html around a bit to match the layout of previous docs builds, and so the links to the docs would work.

For example, the clang docs would be in tools/clang/docs/html, but the link would point to tools/clang/docs/

[tstellar]

Address review comments.

[kuhnel]

llvm/utils/release/build-docs.sh

29

I would not limit the usage of this to releases. I guess this can also be used for any other situation where someone wants to build the documentation locally, e.g. to check if your documentation change is rendered as expected.

61

Yes: https://stackoverflow.com/a/246128

[tstellar]

Don't limit script usage to releases.

[tstellar]

@kuhnel Does this version of the patch look good to you?

[kuhnel]

No more comments from me. However I'm not an expert on bash scripting...

[ljmf00]

I suggest the usage of shellcheck linter. A lot of errors can happen due to e.g. missing double quotes causing word splitting on bash.

[ljmf00]

I left some comments :)

llvm/utils/release/build-docs.sh

26

Use double quotes to prevent word split

31

Use $(...) instead of legacy backticks for subshell. Using backticks is limited to one level of subshell and make the rest of the code consistent.

45

Double quotes

69

POSIX test is not so well defined to allow these XSI extensions in a reliable way. Read this for context: https://github.com/koalaman/shellcheck/wiki/SC2166

86

pushd and popd is not POSIX compliant and are only available via bash, not sh.

llvm/utils/release/build-docs.sh

+#!/bin/sh
+#===-- build-docs.sh - Tag the LLVM release candidates ---------------------===#
+#
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+#===------------------------------------------------------------------------===#
+#
+# Build documentation for LLVM releases.
+#
+# Required Packages:
+# * Fedora:
+#   * dnf install doxygen python3-sphinx texlive-epstopdf ghostscript \
+#                 ninja-build gcc-c++
+#   * pip install sphinx-markdown-tables
+# * Ubuntu:
+#   * apt-get install doxygen sphinx-common python3-recommonmark \
+#             ninja-build graphviz texlive-font-utils
+#   * pip install sphinx-markdown-tables
+#===------------------------------------------------------------------------===#
+
+set -ex
+
+builddir=docs-build
+srcdir=$(readlink -f $(dirname "$(readlink -f "$0")")/../..)
+
+usage() {
+  echo "Build the documentation for an LLVM release.  This only needs to be "
+  echo "done for -final releases."
+  echo "usage: `basename $0`"
+  echo " "
+  echo " -release <num> Fetch the tarball for release <num> and build the "
+  echo "                documentation from that source."
+  echo " -srcdir  <dir> Path to llvm source directory with CMakeLists.txt"
+  echo "                (optional) default: $srcdir"
+}
+
+package_doxygen() {
+
+  project=$1
+  proj_dir=$2
+  output=${project}_doxygen-$release
+
+  mv $builddir/$proj_dir/docs/doxygen/html $output
+  tar -cJf $output.tar.xz $output
+}
+
+
+while [ $# -gt 0 ]; do
+  case $1 in
+    -release )
+      shift
+      release=$1
+      ;;
+    -srcdir )
+      shift
+      custom_srcdir=$1
+      ;;
+    * )
+      echo "unknown option: $1"
+      usage
+      exit 1
+      ;;
+   esac
+   shift
+done
+
+if [ -n "$release" -a -n "$custom_srcdir" ]; then
+  echo "error: Cannot specify both -srcdir and -release options"
+  exit 1
+fi
+
+if [ -n "$custom_srcdir" ]; then
+  srcdir="$custom_srcdir"
+fi
+
+# Set default source directory if one is not supplied
+if [ -n "$release" ]; then
+  git_ref=llvmorg-$release
+  if [ -d llvm-project ]; then
+    echo "error llvm-project directory already exists"
+    exit 1
+  fi
+  mkdir -p llvm-project
+  pushd llvm-project
+  curl -L https://github.com/llvm/llvm-project/archive/$git_ref.tar.gz | tar --strip-components=1 -xzf -
+  popd
+  srcdir="./llvm-project/llvm"
+fi
+
+cmake -G Ninja $srcdir -B $builddir \
+               -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra;lld;libcxx;polly;flang" \
+               -DCMAKE_BUILD_TYPE=Release \
+               -DLLVM_ENABLE_DOXYGEN=ON \
+               -DLLVM_ENABLE_SPHINX=ON \
+               -DLLVM_BUILD_DOCS=ON \
+               -DLLVM_DOXYGEN_SVG=ON \
+               -DSPHINX_WARNINGS_AS_ERRORS=OFF
+
+ninja -C $builddir \
+               docs-clang-html \
+               docs-clang-tools-html \
+               docs-flang-html \
+               docs-libcxx-html \
+               docs-lld-html \
+               docs-llvm-html \
+               docs-polly-html \
+               doxygen-clang \
+               doxygen-clang-tools \
+               doxygen-flang \
+               doxygen-llvm \
+               doxygen-mlir \
+               doxygen-polly
+
+
+package_doxygen llvm .
+package_doxygen clang tools/clang
+package_doxygen clang-tools-extra tools/clang/tools/extra
+package_doxygen flang tools/flang
+
+html_dir=$builddir/html-export/
+
+for d in docs/ tools/clang/docs/ tools/lld/docs/ tools/clang/tools/extra/docs/ projects/libcxx/docs/ tools/polly/docs/ tools/flang/docs/; do
+  mkdir -p $html_dir/$d
+  mv $builddir/$d/html/* $html_dir/$d/
+done