# Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. # SPDX-License-Identifier: Apache-2.0 load("@build_bazel_rules_nodejs//:index.bzl", "nodejs_binary") load("@os_info//:os_info.bzl", "is_linux", "is_windows") load("//rules_daml:daml.bzl", "daml_build_test", "daml_compile", "daml_test") load("@rules_pkg//:pkg.bzl", "pkg_tar") load("@build_environment//:configuration.bzl", "mvn_version", "sdk_version") load("@scala_version//:index.bzl", "scala_major_version") exports_files( [ "configs/html/conf.py", "configs/static/pygments_daml_lexer.py", "configs/static/typescript.py", "scripts/check-closing-quotes.sh", "scripts/check-closing-quotes.sh.allow", "source/tools/export/output-root/Export.daml", "source/tools/export/output-root/args.json", "source/tools/export/output-root/daml.yaml", ], ) nodejs_binary( name = "grunt", data = [ "@npm//grunt-cli", ], entry_point = "@npm//:node_modules/grunt-cli/bin/grunt", ) genrule( name = "theme", srcs = glob( ["theme/**"], exclude = [ "theme/bower_components/**", "theme/node_modules/**", "theme/da_theme/**", ], ) + [ # we need to list all the transitive dependencies here because of https://github.com/bazelbuild/rules_nodejs/issues/1553 "@npm//:node_modules", ], outs = ["da_theme.tar.gz"], cmd = """ cp -rL docs/theme theme cd theme # Make the node_modules available ln -s ../external/npm/node_modules . # Run sass and grunt ../$(execpath @sass_nix//:bin/sass) \\ -I bower_components_static/bourbon/dist \\ -I bower_components_static/neat/app/assets/stylesheets \\ -I bower_components_static/font-awesome/scss \\ -I bower_components_static/wyrm/sass \\ --style compressed \\ --sourcemap=none \\ --update \\ sass:da_theme/static/css ../$(execpath :grunt) build ../$(execpath //bazel_tools/sh:mktgz) ../$@ da_theme """, tools = [ ":grunt", "//bazel_tools/sh:mktgz", "@sass_nix//:bin/sass", ], visibility = ["//visibility:public"], ) if not is_windows else None genrule( name = "hoogle_db", srcs = [ "//compiler/damlc:daml-base-hoogle.txt", "//daml-script/daml:daml-script-hoogle.txt", "//triggers/daml:daml-trigger-hoogle.txt", ], outs = ["hoogle_db.tar.gz"], cmd = """ mkdir hoogle cp -L $(location //compiler/damlc:daml-base-hoogle.txt) hoogle/ cp -L $(location //daml-script/daml:daml-script-hoogle.txt) hoogle/ cp -L $(location //triggers/daml:daml-trigger-hoogle.txt) hoogle/ $(execpath //bazel_tools/sh:mktgz) $@ hoogle """, tools = ["//bazel_tools/sh:mktgz"], ) genrule( name = "sources", srcs = glob(["source/**"]) + [ "//compiler/damlc:daml-base-rst.tar.gz", "//triggers/daml:daml-trigger-rst.tar.gz", "//daml-script/daml:daml-script-rst.tar.gz", "//ledger-api/grpc-definitions:docs", "//:LICENSE", "//:NOTICES", ":generate-docs-error-codes-inventory-into-rst-file", ":generate-docs-error-categories-inventory-into-rst-file", ], outs = ["source.tar.gz"], cmd = """ cp -rL docs/source source # Copy in error inventories # # These files are meant to be only included into other .rst files and so # in order to prevent Sphinx from recognizing them as source files # we append an '.inc' suffix. (See `source_suffix` in `conf.py`.) cp -L -- $(location //docs:generate-docs-error-codes-inventory-into-rst-file) source/app-dev/grpc/error-codes-inventory.rst.inc cp -L -- $(location //docs:generate-docs-error-categories-inventory-into-rst-file) source/app-dev/grpc/error-categories-inventory.rst.inc # Copy in Stdlib mkdir -p source/daml/stdlib tar xf $(location //compiler/damlc:daml-base-rst.tar.gz) \\ --strip-components 1 \\ -C source/daml/stdlib # Copy in daml-trigger documentation mkdir -p source/triggers/api/ tar xf $(location //triggers/daml:daml-trigger-rst.tar.gz) \\ --strip-components 1 \\ -C source/triggers/api/ # Copy in daml-script documentation mkdir -p source/daml-script/api/ tar xf $(location //daml-script/daml:daml-script-rst.tar.gz) \\ --strip-components 1 \\ -C source/daml-script/api/ # Copy in Protobufs cp -rL $(location //ledger-api/grpc-definitions:docs) source/app-dev/grpc/proto-docs.rst # Copy in License and Notices cp -L $(location //:LICENSE) source/LICENSE cp -L $(location //:NOTICES) source/NOTICES $(execpath //bazel_tools/sh:mktgz) $@ source """, tools = ["//bazel_tools/sh:mktgz"], ) genrule( name = "sphinx-source-tree", srcs = [ "configs/static/pygments_daml_lexer.py", "configs/static/typescript.py", "configs/html/conf.py", "configs/pdf/conf.py", "configs/pdf/logo.png", "configs/pdf/index.rst", ":sources", ":theme", "//templates:templates-tarball", "//templates:create-daml-app-docs", "//templates:create-daml-app-test-resources/index.test.ts", ], outs = ["sphinx-source-tree.tar.gz"], cmd = """ set -eou pipefail DIR=$$(mktemp -d) trap "rm -rf $$DIR" EXIT mkdir -p $$DIR/docs mkdir -p $$DIR/docs/configs/static $$DIR/docs/configs/html $$DIR/docs/configs/pdf/fonts cp $(location configs/static/pygments_daml_lexer.py) $$DIR/docs/configs/static cp $(location configs/static/typescript.py) $$DIR/docs/configs/static tar xf $(location :sources) -C $$DIR/docs cp $(location configs/html/conf.py) $$DIR/docs/configs/html cp $(location configs/pdf/conf.py) $$DIR/docs/configs/pdf sed -i "s,__VERSION__,"{sdk}"," $$DIR/docs/configs/html/conf.py sed -i "s,__VERSION__,"{sdk}"," $$DIR/docs/configs/pdf/conf.py mv $$DIR/docs/source/index.rst $$DIR/docs/configs/html cp $(location configs/pdf/index.rst) $$DIR/docs/configs/pdf cp $(location configs/pdf/logo.png) $$DIR/docs/configs/pdf # Copy in theme mkdir -p $$DIR/docs/theme tar xf $(location :theme) -C $$DIR/docs/theme # Copy templates for code snippets in getting started guide CODE_DIR=$$DIR/docs/source/getting-started/code/ mkdir -p $$CODE_DIR tar -zxf $(location //templates:templates-tarball) -C $$CODE_DIR rm -rf $$CODE_DIR/templates-tarball/create-daml-app tar -zxf $(location //templates:create-daml-app-docs) -C $$CODE_DIR/templates-tarball/ # Copy create-daml-app tests mkdir $$CODE_DIR/testing cp $(location //templates:create-daml-app-test-resources/index.test.ts) $$CODE_DIR/testing TEMPLATES_DIR=$$DIR/docs/source/_templates mkdir -p $$TEMPLATES_DIR tar xf $(location //templates:templates-tarball) -C $$TEMPLATES_DIR --strip-components=1 MKTGZ=$$PWD/$(execpath //bazel_tools/sh:mktgz) OUT_PATH=$$PWD/$@ cd $$DIR $$MKTGZ $$OUT_PATH docs """, tools = [ "//bazel_tools/sh:mktgz", ], ) if not is_windows else None [ genrule( name = "sphinx-{}".format(name), srcs = [ ":sphinx-source-tree", ":scripts/check-closing-quotes.sh", ":scripts/check-closing-quotes.sh.allow", ] + (["@glibc_locales//:locale-archive"] if is_linux else []), outs = ["sphinx-{}.tar.gz".format(name)], cmd = (""" export LOCALE_ARCHIVE="$$PWD/$(location @glibc_locales//:locale-archive)" """ if is_linux else "") + """ set -eou pipefail DIR=$$(mktemp -d) mkdir -p $$DIR/source $$DIR/target tar xf $(location sphinx-source-tree) -C $$DIR/source --strip-components=1 mv $$DIR/source/configs/{name}/index.rst $$DIR/source/source/ if ! docs/scripts/check-closing-quotes.sh $$DIR/source docs/scripts/check-closing-quotes.sh.allow; then exit 1 fi export LC_ALL=en_US.UTF-8 export LANG=en_US.UTF-8 # Sphinx 1.8.3 triggers the following warning: # # /nix/store/1v39mhhyn48s251przk2fwcvgm71vfqi-python3.7-sphinx-1.8.3/lib/python3.7/site-packages/sphinx/writers/html.py:462: FutureWarning: # The iterable returned by Node.traverse() # will become an iterator instead of a list in Docutils > 0.16. # target_node = image_nodes and image_nodes[0] or node.parent # # We are using an older Sphinx (1.8.3) with a more recent nixpkgs revision. # Unfortunately, an update is not so easy because Sphinx 2.3.1 breaks # the PDF documentation due to issues with the FreeSerif font in the # fontspec package. So, for now we ignore `FutureWarning`. SPHINX_BUILD_EXIT_CODE=0 # We hide the output unless we get a failure to make the builds less noisy. SPHINX_BUILD_OUTPUT=$$($(location @sphinx_nix//:bin/sphinx-build) -W -b {target} -c $$DIR/source/configs/{name} $$DIR/source/source $$DIR/target 2>&1) || SPHINX_BUILD_EXIT_CODE=$$? if [ "$$SPHINX_BUILD_EXIT_CODE" -ne 0 ]; then >&2 echo "## SPHINX-BUILD OUTPUT:" >&2 echo "$$SPHINX_BUILD_OUTPUT" >&2 echo "## SPHINX-BUILD OUTPUT END" exit 1 fi MKTGZ=$$PWD/$(execpath //bazel_tools/sh:mktgz) OUT_PATH=$$PWD/$@ cd $$DIR $$MKTGZ $$OUT_PATH target """.format( target = target, name = name, ), tools = [ "//bazel_tools/sh:mktgz", "@sphinx_nix//:bin/sphinx-build", ], ) for (name, target) in [ ("html", "html"), ("pdf", "latex"), ] ] if not is_windows else None genrule( name = "pdf-docs", srcs = [ ":sphinx-pdf", ":pdf-fonts", ], outs = ["DigitalAssetSDK.pdf"], cmd = """ set -euo pipefail # Set up tools export PATH="$$( cd "$$(dirname "$(location @imagemagick_nix//:bin/convert)")" ; pwd -P )":$$PATH mkdir out tar -zxf $(location sphinx-pdf) -C out --strip-components=1 # Copy in fonts and build with lualatex cp -L $(locations :pdf-fonts) out/ cd out # run twice to generate all references properly (this is a latex thing...) ../$(location @texlive_nix//:bin/lualatex) -halt-on-error -interaction=batchmode --shell-escape *.tex ../$(location @texlive_nix//:bin/lualatex) -halt-on-error -interaction=batchmode --shell-escape *.tex # NOTE, if you get errors of the following form: # # luaotfload | db : Font names database not found, generating new one. # luaotfload | db : This can take several minutes; please be patient. # luaotfload | db : Reload initiated (formats: otf,ttf,ttc); reason: "File not found: lmroman10-regular.". # # Then the error is most likely not font related. To debug the error # run `bazel build` with `--sandbox_debug`, change into the sandbox # directory and invoke lualatex from there. You will have to replicate # the environment variable setup from above. # # In the past the following issues caused the error message above: # - An update of sphinx in nixpkgs that had to be undone. # - A missing texlive package that had to be added to the Nix derivation. # Move output to target mv DigitalAssetSDK.pdf ../$(location DigitalAssetSDK.pdf)""".format(sdk = sdk_version), tags = ["pdfdocs"], tools = [ "@imagemagick_nix//:bin/convert", "@texlive_nix//:bin/lualatex", ], ) if not is_windows else None filegroup( name = "pdf-fonts", srcs = glob(["configs/pdf/fonts/**"]), ) pkg_tar( name = "pdf-fonts-tar", srcs = [":pdf-fonts"], extension = "tar.gz", ) genrule( name = "non-sphinx-html-docs", srcs = [ ":hoogle_db.tar.gz", "//language-support/java:javadoc", "//language-support/ts/daml-react:docs", "//language-support/ts/daml-ledger:docs", "//language-support/ts/daml-types:docs", "@daml-cheat-sheet//:site", ":redirects", "error.html", ], outs = ["non-sphinx-html-docs.tar.gz"], cmd = """ set -eou pipefail DIR=$$(mktemp -d) trap "rm -rf DIR" EXIT mkdir -p $$DIR/html/app-dev/bindings-java/javadocs # Copy Javadoc using unzip to avoid having to know the path to the 'jar' binary. Note flag to overwrite unzip -q -o $(locations //language-support/java:javadoc) -d $$DIR/html/app-dev/bindings-java/javadocs # Remove JAR metadata rm -r $$DIR/html/app-dev/bindings-java/javadocs/META-INF # Copy generated documentation for typescript libraries mkdir -p $$DIR/html/app-dev/bindings-ts/daml-react mkdir -p $$DIR/html/app-dev/bindings-ts/daml-ledger mkdir -p $$DIR/html/app-dev/bindings-ts/daml-types tar -xzf $(location //language-support/ts/daml-react:docs) --strip-components 1 -C $$DIR/html/app-dev/bindings-ts/daml-react/ tar -xzf $(location //language-support/ts/daml-ledger:docs) --strip-components 1 -C $$DIR/html/app-dev/bindings-ts/daml-ledger/ tar -xzf $(location //language-support/ts/daml-types:docs) --strip-components 1 -C $$DIR/html/app-dev/bindings-ts/daml-types/ # The generated docs of the typescript libraries are published at two places: The npm # registry and on docs.daml.com. The docs at the npm registry contain a link pointing # to docs.daml.com. We remove it for the version published at docs.daml.com as it would be # pointing to itself. sed -i -e 's,^.*\\(Comprehensive documentation\\|