Generate hoogle docs for daml script/triggers (#7371)

* Generate hoogle docs for daml script/triggers This PR switches over the documentation generation for daml script and daml triggers to the multi-page format we already use for the standard library and extends it to also generate hoogle documentation. All 3 hoogle files are combined in a single hoogle_db.tar.gz archive. Since the location in the multi-page format is different, I’ve added redirects. I verified locally, that I can generate the hoogle database and that the links point to the right places. changelog_begin changelog_end * Fix baseurl for daml-stdlib changelog_begin changelog_end
digital-asset · Sep 10, 2020 · c0b6851 · c0b6851
1 parent 4b13b18
commit c0b6851
Show file tree

Hide file tree

Showing 13 changed files with 163 additions and 39 deletions.
diff --git a/compiler/damlc/base-hoogle-template.txt b/compiler/damlc/base-hoogle-template.txt
@@ -1,4 +1,4 @@
--- Hoogle documentation for DAML, generated by daml-ghc.
+-- Hoogle documentation for DAML, generated by damlc
 -- See Hoogle, http://www.haskell.org/hoogle/
 
 -- (C) Copyright 2020 Digital Asset (Switzerland) GmbH and/or its affiliates.
@@ -9,4 +9,4 @@
 @package daml-stdlib
 @version 1.2.0
 
-{{{body}}}
+{{{body}}}
diff --git a/daml-script/daml/BUILD.bazel b/daml-script/daml/BUILD.bazel
@@ -63,17 +63,52 @@ filegroup(
 )
 
 genrule(
-    name = "daml-script-rst-docs",
-    srcs = glob(["**/*.daml"]) + [":daml-script-rst-template.rst"],
-    outs = ["daml-script.rst"],
+    name = "daml-script-docs",
+    srcs = [
+        ":daml-script.json",
+        ":daml-script-rst-template.rst",
+        ":daml-script-index-template.rst",
+        ":daml-script-hoogle-template.txt",
+    ],
+    outs = [
+        "daml-script-rst.tar.gz",
+        "daml-script-hoogle.txt",
+        "daml-script-anchors.json",
+    ],
     cmd = """
         $(location //compiler/damlc) -- docs \
-            --combine \
-            --output=$(location :daml-script.rst) \
+            --output=daml-script-rst \
+            --input-format=json \\
             --format=Rst \
             --template=$(location :daml-script-rst-template.rst) \
+            --index-template=$(location :daml-script-index-template.rst) \\
+            --hoogle-template=$(location :daml-script-hoogle-template.txt) \\
+            --base-url=https://docs.daml.com/daml-script/api/ \\
+            --output-hoogle=$(location :daml-script-hoogle.txt) \\
+            --output-anchor=$(location :daml-script-anchors.json) \\
+            $(location :daml-script.json)
+        $(execpath //bazel_tools/sh:mktgz) $(location :daml-script-rst.tar.gz) daml-script-rst
+    """,
+    tools = [
+        "//bazel_tools/sh:mktgz",
+        "//compiler/damlc",
+    ],
+    visibility = ["//visibility:public"],
+)
+
+genrule(
+    name = "daml-script-json-docs",
+    srcs = glob(["**/*.daml"]),
+    outs = ["daml-script.json"],
+    cmd = """
+        $(location //compiler/damlc) -- docs \
+            --output=$(OUTS) \
+            --package-name=daml-script \
+            --format=Json \
             $(location Daml/Script.daml)
     """,
-    tools = ["//compiler/damlc"],
+    tools = [
+        "//compiler/damlc",
+    ],
     visibility = ["//visibility:public"],
 )
diff --git a/daml-script/daml/daml-script-hoogle-template.txt b/daml-script/daml/daml-script-hoogle-template.txt
@@ -0,0 +1,12 @@
+-- Hoogle documentation for DAML, generated by damlc
+-- See Hoogle, http://www.haskell.org/hoogle/
+
+-- (C) Copyright 2020 Digital Asset (Switzerland) GmbH and/or its affiliates.
+-- All rights reserved. Any unauthorized use, duplication or distribution is strictly prohibited.
+
+-- | DAML Script library.
+@url {{base-url}}
+@package daml-script
+@version 1.2.0
+
+{{{body}}}
diff --git a/daml-script/daml/daml-script-index-template.rst b/daml-script/daml/daml-script-index-template.rst
@@ -0,0 +1,11 @@
+.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+.. _daml-script-api-docs:
+
+DAML Script Library
+====================
+
+The DAML Script library defines the API used to implement DAML scripts. See :doc:`/daml-script/index`:: for more information on DAML script.
+
+{{{body}}}
diff --git a/daml-script/daml/daml-script-rst-template.rst b/daml-script/daml/daml-script-rst-template.rst
@@ -1,11 +1,4 @@
 .. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
 .. SPDX-License-Identifier: Apache-2.0
 
-.. _daml-script-api-docs:
-
-DAML Script Library
-====================
-
-The DAML Script library defines the API used to implement DAML scripts. See :doc:`index`:: for more information on DAML script.
-
 {{{body}}}
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
@@ -253,12 +253,30 @@ genrule(
     ],
 ) 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-docs",
-        "//daml-script/daml:daml-script-rst-docs",
+        "//triggers/daml:daml-trigger-rst.tar.gz",
+        "//daml-script/daml:daml-script-rst.tar.gz",
         "//ledger-api/grpc-definitions:docs",
         "//:LICENSE",
         "//:NOTICES",
@@ -274,10 +292,16 @@ genrule(
             -C source/daml/stdlib
 
         # Copy in daml-trigger documentation
-        cp -rL $(location //triggers/daml:daml-trigger-rst-docs) source/triggers/trigger-docs.rst
+        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
-        cp -rL $(location //daml-script/daml:daml-script-rst-docs) source/daml-script/daml-script-docs.rst
+        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
@@ -362,7 +386,7 @@ genrule(
     ]) + [
         ":sources",
         ":theme",
-        "//compiler/damlc:daml-base-hoogle.txt",
+        ":hoogle_db.tar.gz",
         "//language-support/java:javadoc",
         "//language-support/ts/daml-react:docs",
         "//language-support/ts/daml-ledger:docs",
@@ -443,8 +467,7 @@ genrule(
         tar -xzf ../$(location @daml-cheat-sheet//:site) --strip-components 1 -C html/cheat-sheet
 
         # Copy in hoogle DB
-        mkdir -p html/hoogle_db
-        cp -rL ../$(location //compiler/damlc:daml-base-hoogle.txt) html/hoogle_db/base.txt
+        cp -L ../$(location :hoogle_db.tar.gz) html/hoogle_db.tar.gz
 
         ../$(execpath //bazel_tools/sh:mktgz) ../$@ html
         """.format(sdk = sdk_version),

diff --git a/docs/redirects.map b/docs/redirects.map
@@ -813,3 +813,5 @@ gsg.html -> /getting-started/installation.html
 getting-started/quickstart.html -> /getting-started/index.html
 app-dev/authentication.html -> /app-dev/authorization.html
 daml/intro/2_Scenario.html -> /daml/intro/2_DamlScript.html
+daml-script/daml-script-docs.html -> /daml-script/api/index.html
+triggers/trigger-docs.html -> /triggers/api/index.html
diff --git a/docs/source/daml-script/index.rst b/docs/source/daml-script/index.rst
@@ -7,7 +7,7 @@ DAML Script
 .. toctree::
    :hidden:
 
-   daml-script-docs
+   api/index
 
 DAML scenarios provide a simple way for testing DAML models
 and getting quick feedback in DAML studio. However, scenarios are run

diff --git a/docs/source/triggers/index.rst b/docs/source/triggers/index.rst
@@ -7,7 +7,7 @@ DAML Triggers - Off-Ledger Automation in DAML
 .. toctree::
    :hidden:
 
-   trigger-docs
+   api/index
 
 **WARNING:** DAML Triggers are an early access feature that is actively
 being designed and is *subject to breaking changes*.

diff --git a/triggers/daml/BUILD.bazel b/triggers/daml/BUILD.bazel
@@ -70,12 +70,11 @@ filegroup(
 )
 
 genrule(
-    name = "daml-trigger-rst-docs",
+    name = "daml-trigger-json-docs",
     srcs = glob(["**/*.daml"]) + [
-        ":daml-trigger-rst-template.rst",
         "//daml-script/daml:daml-script",
     ],
-    outs = ["daml-trigger.rst"],
+    outs = ["daml-trigger.json"],
     cmd = """
           TMP_DIR=$$(mktemp -d)
           mkdir -p $$TMP_DIR/daml/Daml/Trigger
@@ -95,15 +94,14 @@ dependencies:
   - daml-script.dar
 EOF
         DAMLC=$$PWD/$(location //compiler/damlc)
-        TEMPLATE=$$PWD/$(location :daml-trigger-rst-template.rst)
-        RST=$$PWD/$(location :daml-trigger.rst)
+        JSON=$$PWD/$(location :daml-trigger.json)
         cd $$TMP_DIR
         $$DAMLC init
         $$DAMLC -- docs \
             --combine \
-            --output=$$RST \
-            --format=Rst \
-            --template=$$TEMPLATE \
+            --output=$$JSON \
+            --format=Json \
+            --package-name=daml-trigger \
             $$TMP_DIR/daml/Daml/Trigger.daml \
             $$TMP_DIR/daml/Daml/Trigger/Assert.daml \
             $$TMP_DIR/daml/Daml/Trigger/LowLevel.daml
@@ -115,3 +113,37 @@ EOF
     tools = ["//compiler/damlc"],
     visibility = ["//visibility:public"],
 )
+
+genrule(
+    name = "daml-trigger-docs",
+    srcs = [
+        ":daml-trigger.json",
+        ":daml-trigger-rst-template.rst",
+        ":daml-trigger-index-template.rst",
+        ":daml-trigger-hoogle-template.txt",
+    ],
+    outs = [
+        "daml-trigger-rst.tar.gz",
+        "daml-trigger-hoogle.txt",
+        "daml-trigger-anchors.json",
+    ],
+    cmd = """
+        $(location //compiler/damlc) -- docs \
+            --output=daml-trigger-rst \
+            --input-format=json \\
+            --format=Rst \
+            --template=$(location :daml-trigger-rst-template.rst) \
+            --index-template=$(location :daml-trigger-index-template.rst) \\
+            --hoogle-template=$(location :daml-trigger-hoogle-template.txt) \\
+            --base-url=https://docs.daml.com/triggers/api/ \\
+            --output-hoogle=$(location :daml-trigger-hoogle.txt) \\
+            --output-anchor=$(location :daml-trigger-anchors.json) \\
+            $(location :daml-trigger.json)
+        $(execpath //bazel_tools/sh:mktgz) $(location :daml-trigger-rst.tar.gz) daml-trigger-rst
+    """,
+    tools = [
+        "//bazel_tools/sh:mktgz",
+        "//compiler/damlc",
+    ],
+    visibility = ["//visibility:public"],
+)
diff --git a/triggers/daml/daml-trigger-hoogle-template.txt b/triggers/daml/daml-trigger-hoogle-template.txt
@@ -0,0 +1,12 @@
+-- Hoogle documentation for DAML, generated by damlc
+-- See Hoogle, http://www.haskell.org/hoogle/
+
+-- (C) Copyright 2020 Digital Asset (Switzerland) GmbH and/or its affiliates.
+-- All rights reserved. Any unauthorized use, duplication or distribution is strictly prohibited.
+
+-- | DAML Trigger library.
+@url {{base-url}}
+@package daml-trigger
+@version 1.2.0
+
+{{{body}}}
diff --git a/triggers/daml/daml-trigger-index-template.rst b/triggers/daml/daml-trigger-index-template.rst
@@ -0,0 +1,11 @@
+.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+.. _daml-trigger-api-docs:
+
+DAML Trigger Library
+====================
+
+The DAML Trigger library defines the API used to declare a DAML trigger. See :doc:`/triggers/index`:: for more information on DAML triggers.
+
+{{{body}}}
diff --git a/triggers/daml/daml-trigger-rst-template.rst b/triggers/daml/daml-trigger-rst-template.rst
@@ -1,11 +1,4 @@
 .. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
 .. SPDX-License-Identifier: Apache-2.0
 
-.. _daml-trigger-api-docs:
-
-DAML Trigger Library
-====================
-
-The DAML Trigger library defines the API used to declare a DAML trigger. See :doc:`index`:: for more information on DAML triggers.
-
 {{{body}}}