daml/docs/BUILD.bazel
Nemanja ff926d0a0f
TypeScript lexer for TS syntax highlighting (#4900)
* Resolves #4304

Added highlighting to the application architecture section

Highlighter that works

The latest highlighter

* Added the lexer to pdf and html and restructured how conf.py is called within the theme

* Added copyright headers

* add typescript.py to srcs

changelog_begin
changelog_end

Co-authored-by: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>
2020-03-13 16:46:23 +01:00

679 lines
22 KiB
Python

# Copyright (c) 2020 The DAML Authors. 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_compile", "daml_test")
load("//rules_daml:daml-build.bzl", "daml_build_test")
load("@bazel_tools//tools/build_defs/pkg:pkg.bzl", "pkg_tar")
load("@build_environment//:configuration.bzl", "mvn_version", "sdk_version")
nodejs_binary(
name = "grunt",
data = [
"@npm//grunt-cli",
"@npm//matchdep",
],
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//acorn",
"@npm//acorn-dynamic-import",
"@npm//acorn-node",
"@npm//acorn-walk",
"@npm//ansi-regex",
"@npm//ansi-styles",
"@npm//anymatch",
"@npm//assert",
"@npm//async",
"@npm//async-each",
"@npm//balanced-match",
"@npm//basic-auth",
"@npm//batch",
"@npm//binary-extensions",
"@npm//body",
"@npm//brace-expansion",
"@npm//browserify",
"@npm//browserify-cache-api",
"@npm//browserify-incremental",
"@npm//browserify-zlib",
"@npm//browser-pack",
"@npm//browser-resolve",
"@npm//buffer",
"@npm//buffer-from",
"@npm//cached-path-relative",
"@npm//chalk",
"@npm//chokidar",
"@npm//coffeescript",
"@npm//color-convert",
"@npm//colors",
"@npm//combine-source-map",
"@npm//concat-map",
"@npm//concat-stream",
"@npm//connect",
"@npm//connect-livereload",
"@npm//console-browserify",
"@npm//constants-browserify",
"@npm//continuable-cache",
"@npm//convert-source-map",
"@npm//core-util-is",
"@npm//cross-spawn",
"@npm//crypto-browserify",
"@npm//dargs",
"@npm//dash-ast",
"@npm//dateformat",
"@npm//defined",
"@npm//depd",
"@npm//deps-sort",
"@npm//destroy",
"@npm//detective",
"@npm//domain-browser",
"@npm//duplexer",
"@npm//duplexer2",
"@npm//ee-first",
"@npm//encodeurl",
"@npm//error",
"@npm//escape-html",
"@npm//escape-string-regexp",
"@npm//etag",
"@npm//eventemitter2",
"@npm//events",
"@npm//exit",
"@npm//faye-websocket",
"@npm//figures",
"@npm//file-sync-cmp",
"@npm//findup-sync",
"@npm//fresh",
"@npm//fs.realpath",
"@npm//function-bind",
"@npm//gaze",
"@npm//get-assigned-identifiers",
"@npm//getobject",
"@npm//glob",
"@npm//glob-parent",
"@npm//globule",
"@npm//graceful-fs",
"@npm//grunt",
"@npm//grunt-banner",
"@npm//grunt-browserify",
"@npm//grunt-contrib-clean",
"@npm//grunt-contrib-connect",
"@npm//grunt-contrib-copy",
"@npm//grunt-contrib-sass",
"@npm//grunt-contrib-uglify",
"@npm//grunt-contrib-watch",
"@npm//grunt-exec",
"@npm//grunt-legacy-log",
"@npm//grunt-legacy-log-utils",
"@npm//grunt-legacy-util",
"@npm//grunt-open",
"@npm//gzip-size",
"@npm//has",
"@npm//has-ansi",
"@npm//has-flag",
"@npm//hooker",
"@npm//htmlescape",
"@npm//http-parser-js",
"@npm//https-browserify",
"@npm//iconv-lite",
"@npm//inflight",
"@npm//inherits",
"@npm//inline-source-map",
"@npm//insert-module-globals",
"@npm//is-binary-path",
"@npm//is-number-like",
"@npm//is-wsl",
"@npm//jsonparse",
"@npm//json-stable-stringify",
"@npm//JSONStream",
"@npm//js-yaml",
"@npm//labeled-stream-splicer",
"@npm//lodash",
"@npm//lodash.isfinite",
"@npm//lodash.memoize",
"@npm//lru-cache",
"@npm//matchdep",
"@npm//maxmin",
"@npm//mime-db",
"@npm//mime-types",
"@npm//minimatch",
"@npm//mkdirp",
"@npm//module-deps",
"@npm//morgan",
"@npm//node-http2",
"@npm//nopt",
"@npm//normalize-path",
"@npm//number-is-nan",
"@npm//object-assign",
"@npm//once",
"@npm//on-finished",
"@npm//on-headers",
"@npm//opn",
"@npm//os-browserify",
"@npm//parents",
"@npm//parseurl",
"@npm//path-browserify",
"@npm//path-dirname",
"@npm//path-is-absolute",
"@npm//path-platform",
"@npm//portscanner",
"@npm//pretty-bytes",
"@npm//process",
"@npm//process-nextick-args",
"@npm//querystring-es3",
"@npm//readable-stream",
"@npm//readdirp",
"@npm//read-only-stream",
"@npm//remove-trailing-separator",
"@npm//rimraf",
"@npm//safe-buffer",
"@npm//safe-json-parse",
"@npm//safer-buffer",
"@npm//serve-index",
"@npm//shasum",
"@npm//sprintf-js",
"@npm//statuses",
"@npm//stream-browserify",
"@npm//stream-combiner2",
"@npm//stream-http",
"@npm//stream-splicer",
"@npm//string_decoder",
"@npm//string-template",
"@npm//strip-ansi",
"@npm//supports-color",
"@npm//syntax-error",
"@npm//through",
"@npm//through2",
"@npm//timers-browserify",
"@npm//tiny-lr",
"@npm//tty-browserify",
"@npm//uglify-js",
"@npm//umd",
"@npm//undeclared-identifiers",
"@npm//underscore.string",
"@npm//unpipe",
"@npm//upath",
"@npm//uri-path",
"@npm//url",
"@npm//util",
"@npm//util-deprecate",
"@npm//utils-merge",
"@npm//vm-browserify",
"@npm//watchify",
"@npm//websocket-driver",
"@npm//websocket-extensions",
"@npm//wrappy",
"@npm//xtend",
],
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
../$(location @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
../$(location :grunt) build
tar \
--owner=1000 \
--group=1000 \
--mtime=1337 \
--no-acls \
--no-xattrs \
--no-selinux \
--sort=name \
-czf ../$(location da_theme.tar.gz) \
da_theme
""",
tools = [
":grunt",
"@sass_nix//:bin/sass",
],
) if not is_windows else None
genrule(
name = "sources",
srcs = glob(["source/**"]) + [
"//compiler/damlc:daml-base-rst-docs",
"//triggers/daml:daml-trigger-rst-docs",
"//daml-script/daml:daml-script-rst-docs",
"//ledger-api/grpc-definitions:docs",
"//:LICENSE",
"//:NOTICES",
],
outs = ["source.tar.gz"],
cmd = """
cp -rL docs/source source
# Copy in Stdlib
cp -rL $(location //compiler/damlc:daml-base-rst-docs) source/daml/reference/base.rst
# Copy in daml-trigger documentation
cp -rL $(location //triggers/daml:daml-trigger-rst-docs) source/triggers/trigger-docs.rst
# Copy in daml-script documentation
cp -rL $(location //daml-script/daml:daml-script-rst-docs) source/daml-script/daml-script-docs.rst
# 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
tar -zcf $(location source.tar.gz) source
""",
)
genrule(
name = "pdf-docs",
srcs = glob([
"configs/pdf/**",
"configs/static/pygments_daml_lexer.py",
"configs/static/typescript.py",
]) + [
":sources",
],
outs = ["DigitalAssetSDK.pdf"],
cmd = ("""
export LOCALE_ARCHIVE="$$PWD/$(location @glibc_locales//:locale-archive)"
""" if is_linux else "") + """
set -euo pipefail
# Set up tools
export PATH="$$( cd "$$(dirname "$(location @imagemagick_nix//:bin/convert)")" ; pwd -P )":$$PATH
# Copy files into the right structure and remove symlinks
tar -zxf $(location sources) -C .
cp -L docs/configs/pdf/index.rst source/
cp -L docs/configs/pdf/conf.py source/
cp -L docs/configs/pdf/logo.png source/
cp -rL docs/configs/static ./
# Build with Sphinx
sed -i "s,__VERSION__,"{sdk}"," source/conf.py
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8
$(location @sphinx_nix//:bin/sphinx-build) -b latex source out
# Copy in fonts and build with lualatex
cp -L docs/configs/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
# Move output to target
mv DigitalAssetSDK.pdf ../$(location DigitalAssetSDK.pdf)""".format(sdk = sdk_version),
tags = ["pdfdocs"],
tools =
[
"@texlive_nix//:bin/lualatex",
"@sphinx_nix//:bin/sphinx-build",
"@imagemagick_nix//:bin/convert",
] + (["@glibc_locales//:locale-archive"] if is_linux else []),
) if not is_windows else None
genrule(
name = "docs-no-pdf",
srcs = glob([
"configs/html/**",
"configs/static/pygments_daml_lexer.py",
"configs/static/typescript.py",
]) + [
":sources",
":theme",
"//compiler/damlc:daml-base-rst-docs",
"//compiler/damlc:daml-base-hoogle-docs",
"//language-support/java:javadoc",
"//language-support/ts/daml-react:docs",
"//language-support/ts/daml-ledger:docs",
"//language-support/ts/daml-types:docs",
],
outs = ["html-only.tar.gz"],
cmd = ("""
export LOCALE_ARCHIVE="$$PWD/$(location @glibc_locales//:locale-archive)"
""" if is_linux else "") + """
# Copy files into the right structure and remove symlinks
mkdir build
cp -rL docs build
tar -zxf $(location sources) -C build/docs
# Copy in theme
mkdir -p build/docs/theme
tar -zxf $(location :theme) -C build/docs/theme
# Build with Sphinx
cd build
sed -i "s,__VERSION__,"{sdk}"," docs/configs/html/conf.py
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8
WARNINGS=$$(../$(location @sphinx_nix//:bin/sphinx-build) -c docs/configs/html docs/source html 2>&1 | \
grep -Ei "warning:" || true)
if [ "$$WARNINGS" != "" ]; then
echo "$$WARNINGS"
exit 1
fi
# Copy Javadoc using unzip to avoid having to know the path to the 'jar' binary. Note flag to overwrite
unzip -o ../$(locations //language-support/java:javadoc) -d html/app-dev/bindings-java/javadocs
# Remove JAR metadata
rm -r html/app-dev/bindings-java/javadocs/META-INF
# Copy generated documentation for typescript libraries
mkdir -p html/app-dev/bindings-ts/daml-react
mkdir -p html/app-dev/bindings-ts/daml-ledger
mkdir -p html/app-dev/bindings-ts/daml-types
tar -xzf ../$(location //language-support/ts/daml-react:docs) --strip-components 1 -C html/app-dev/bindings-ts/daml-react/
tar -xzf ../$(location //language-support/ts/daml-ledger:docs) --strip-components 1 -C html/app-dev/bindings-ts/daml-ledger/
tar -xzf ../$(location //language-support/ts/daml-types:docs) --strip-components 1 -C html/app-dev/bindings-ts/daml-types/
# Copy in hoogle DB
mkdir -p html/hoogle_db
cp -rL ../$(location //compiler/damlc:daml-base-hoogle-docs) html/hoogle_db/base.txt
tar -zcf ../$(location html-only.tar.gz) html
""".format(sdk = sdk_version),
tools =
["@sphinx_nix//:bin/sphinx-build"] +
(["@glibc_locales//:locale-archive"] if is_linux else []),
) if not is_windows else None
genrule(
name = "redirects",
srcs = [
"redirects.map",
"redirect_template.html",
],
outs = ["redirects.tar.gz"],
cmd = """
mkdir redirects
while read l; do
from=$$(awk -F' -> ' '{print $$1}' <<<$$l)
to=$$(awk -F' -> ' '{print $$2}' <<<"$$l")
if [ $$to ]
then
mkdir -p redirects/$$(dirname $$from)
cp -L docs/redirect_template.html redirects/$$from
sed -i -e "s,__URL__,$${to}," redirects/$$from
fi
done <docs/redirects.map
tar -zcf $(location redirects.tar.gz) redirects
""",
)
genrule(
name = "docs",
srcs = [
":docs-no-pdf",
":pdf-docs",
":redirects",
"error.html",
],
outs = ["html.tar.gz"],
cmd = """
VERSION_DATE=$$(cat bazel-out/stable-status.txt | grep STABLE_VERSION_DATE | head -1 | cut -f 2 -d' ')
tar -zxf $(location :redirects)
tar -zxf $(location :docs-no-pdf)
cp -rn redirects/* html
cp -L docs/error.html html
cd html
find . -name '*.html' | sort | sed -e 's,^\\./,https://docs.daml.com/,' > sitemap
SMHEAD=\"{head}\"
SMITEM=\"{item}\"
SMFOOT=\"{foot}\"
echo $$SMHEAD > sitemap.xml
while read item; do
echo $$SMITEM | sed -e "s,%DATE%,$${{VERSION_DATE}}," | sed -e "s,%LOC%,$${{item}}," >> sitemap.xml
done < sitemap
rm sitemap
echo $$SMFOOT >> sitemap.xml
echo {{ \\"{version}\\" : \\"{version}\\" }} > versions.json
cd ..
cp -L $(location :pdf-docs) html/_downloads
# Remove Sphinx build products
rm -rf .buildinfo .doctrees objects.inv
tar -zcf $(location html.tar.gz) html
""".format(
head = """<?xml version='1.0' encoding='UTF-8'?><urlset xmlns='http://www.sitemaps.org/schemas/sitemap/0.9' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation='http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd'>""",
item = """<url><loc>%LOC%</loc><lastmod>%DATE%</lastmod><changefreq>daily</changefreq><priority>0.8</priority></url>""",
foot = """</urlset>""",
version = sdk_version,
),
stamp = 1,
tags = ["pdfdocs"],
) if not is_windows else None
filegroup(
name = "daml-assistant-iou-setup",
srcs = glob(
["source/getting-started/quickstart/template-root/*"],
# excluding quickstart-java stuff
exclude = [
"source/getting-started/quickstart/template-root/src",
"source/getting-started/quickstart/template-root/pom.xml",
],
exclude_directories = 0,
),
visibility = ["//visibility:public"],
)
genrule(
name = "quickstart-java",
srcs = glob(["source/getting-started/quickstart/template-root/**"]),
outs = ["quickstart-java.tar.gz"],
cmd = """
mkdir -p quickstart-java
cp -rL docs/source/getting-started/quickstart/template-root/* quickstart-java/
sed -i "s/__VERSION__/{mvn}/" quickstart-java/pom.xml
tar zcf $@ quickstart-java
""".format(mvn = mvn_version),
visibility = ["//visibility:public"],
)
load("//language-support/java/codegen:codegen.bzl", "dar_to_java")
genrule(
name = "quickstart-model",
srcs = [
"//docs:source/getting-started/quickstart/template-root/daml/Main.daml",
"//docs:source/getting-started/quickstart/template-root/daml/Iou.daml",
"//docs:source/getting-started/quickstart/template-root/daml/IouTrade.daml",
"//docs:source/getting-started/quickstart/template-root/daml/Setup.daml",
"//daml-script/daml:daml-script.dar",
],
outs = ["quickstart-model.dar"],
cmd = """
set -eou pipefail
TMP_DIR=$$(mktemp -d)
mkdir -p $$TMP_DIR/daml
cp -R -L $(location //docs:source/getting-started/quickstart/template-root/daml/Main.daml) $$TMP_DIR/daml/
cp -R -L $(location //docs:source/getting-started/quickstart/template-root/daml/Iou.daml) $$TMP_DIR/daml/
cp -R -L $(location //docs:source/getting-started/quickstart/template-root/daml/IouTrade.daml) $$TMP_DIR/daml/
cp -R -L $(location //docs:source/getting-started/quickstart/template-root/daml/Setup.daml) $$TMP_DIR/daml/
cp -L $(location //daml-script/daml:daml-script.dar) $$TMP_DIR/
cat << EOF > $$TMP_DIR/daml.yaml
sdk-version: {sdk}
name: quickstart-model
source: daml
version: 0.0.1
dependencies:
- daml-stdlib
- daml-prim
- daml-script.dar
build-options: ["--ghc-option", "-Werror"]
EOF
$(location //compiler/damlc) build --project-root=$$TMP_DIR -o $$PWD/$(location quickstart-model.dar)
rm -rf $$TMP_DIR
""".format(sdk = sdk_version),
tools = ["//compiler/damlc"],
visibility = ["//visibility:public"],
)
dar_to_java(
name = "quickstart-model",
src = "quickstart-model.dar",
package_prefix = "com.digitalasset.quickstart.model",
)
java_binary(
name = "quickstart-java-lib",
srcs = glob(["source/getting-started/quickstart/template-root/src/main/java/**/*.java"]) + [":quickstart-model-srcjar"],
main_class = "com.digitalasset.quickstart.iou.IouMain",
deps = [
"//daml-lf/archive:daml_lf_dev_archive_java_proto",
"//language-support/java/bindings:bindings-java",
"//language-support/java/bindings-rxjava",
"@maven//:ch_qos_logback_logback_classic",
"@maven//:com_google_code_gson_gson",
"@maven//:com_google_guava_guava",
"@maven//:com_google_protobuf_protobuf_java",
"@maven//:com_sparkjava_spark_core",
"@maven//:io_reactivex_rxjava2_rxjava",
"@maven//:org_slf4j_slf4j_api",
],
)
daml_test(
name = "ledger-api-daml-test",
srcs = glob(["source/app-dev/code-snippets/**/*.daml"]),
)
daml_test(
name = "bindings-java-daml-test",
srcs = glob(["source/app-dev/bindings-java/code-snippets/**/*.daml"]),
)
daml_test(
name = "patterns-daml-test",
srcs = glob(["source/daml/patterns/daml/**/*.daml"]),
)
daml_test(
name = "daml-studio-daml-test",
srcs = glob(["source/daml/daml-studio/daml/**/*.daml"]),
)
daml_test(
name = "daml-ref-daml-test",
timeout = "long",
srcs = glob(["source/daml/code-snippets/**/*.daml"]),
)
daml_test(
name = "introduction-daml-test",
srcs = glob(["source/getting-started/introduction/code/**/*.daml"]),
)
daml_test(
name = "quickstart-daml-test",
srcs = glob(
include = ["source/getting-started/quickstart/template-root/daml/**/*.daml"],
# excluding Setup.daml, because it doesn't contain any scenarios,
# and we cannot conveniently add daml-script as a dependency for daml_test
exclude = ["source/getting-started/quickstart/template-root/daml/Setup.daml"],
),
)
daml_test(
name = "ledger-model-daml-test",
srcs = glob(["source/concepts/ledger-model/daml/**/*.daml"]),
)
daml_test(
name = "java-bindings-docs-daml-test",
srcs = glob(["source/app-dev/bindings-java/daml/**/*.daml"]),
)
daml_test(
name = "daml-intro-daml-test",
srcs = glob(["source/daml/intro/daml/**/*.daml"]),
)
daml_build_test(
name = "daml-upgrade-example-v1",
project_dir = "source/upgrade/example/coin-1.0.0",
)
daml_build_test(
name = "daml-upgrade-example-v2",
project_dir = "source/upgrade/example/coin-2.0.0",
)
daml_build_test(
name = "daml-upgrade-example-upgrade",
dar_dict = {
":daml-upgrade-example-v1": "path/to/coin-1.0.0.dar",
":daml-upgrade-example-v2": "path/to/coin-2.0.0.dar",
},
project_dir = "source/upgrade/example/coin-upgrade",
)
filegroup(
name = "daml-intro-1",
srcs = glob(
["source/daml/intro/daml/1_Token/**/*"],
# excluding quickstart-java stuff
exclude = [
"source/getting-started/quickstart/template-root/src",
"source/getting-started/quickstart/template-root/pom.xml",
],
exclude_directories = 0,
),
visibility = ["//visibility:public"],
)
pkg_tar(
name = "daml-intro-templates",
srcs = glob(["source/daml/intro/daml/**"]),
strip_prefix = "source/daml/intro/daml",
visibility = ["//visibility:public"],
)
pkg_tar(
name = "copy-trigger-template",
srcs = glob(
["source/triggers/template-root/**"],
exclude = ["**/*~"],
),
strip_prefix = "source/triggers/template-root",
visibility = ["//visibility:public"],
)
pkg_tar(
name = "script-example-template",
srcs = glob(
["source/daml-script/template-root/**"],
exclude = ["**/*~"],
),
strip_prefix = "source/daml-script/template-root",
visibility = ["//visibility:public"],
)
exports_files([
"source/triggers/template-root/src/CopyTrigger.daml",
"source/daml-script/template-root/src/ScriptExample.daml",
])