Build links to the Flows IDE for rendered pages

Update the `build-doc-bundle` script to create a gzip-encoded link to
the example flows in the Flows IDE.

The IDE link is passed to the asciidoc content by setting it as an
attribute of the doc, which the content can then reference in a
`link:` directive.
For now, as a simple matter of simplicity and uniformity, the link is
dropped, unadorned, at the top of each page where it is supported.

Because the compute examples contain multiple definitions and
therefore can't build simple links, an exclude config is supported to
disable the links for these examples.

Author: sirosen

compute_transfer_examples/tar_and_transfer/.doc_config.yaml

@@ -7,6 +7,7 @@ short_description: |
     Two examples are included here, one in which the files are located on the
     server which runs Globus Compute, and one in which the files are on a user's
     machine and must be moved to the Compute host.
+include_ide_link: false
 
 example_dir: 'compute_tar_and_transfer'
 append_source_blocks: false

compute_transfer_examples/tar_and_transfer/collection_transfer_requires_flow/.doc_config.yaml

@@ -12,6 +12,7 @@ short_description: |
     They are expected to be invoked from the Globus webapp when initating a transfer
     where the source / destination collections have an `associated_flow_policy`
     with this flow.
+include_ide_link: false
 
 example_dir: 'collection_transfer_requires_flow'
 append_source_blocks: false
@@ -29,4 +30,4 @@ include_files:
   - 'compute_transfer_example_2_schema.json'
   - 'register_compute_function.py'
 
-menu_weight: 400
+menu_weight: 400

support/build-doc-bundle.py

@@ -7,14 +7,18 @@
 
 from __future__ import annotations
 
+import base64
 import dataclasses
 import glob
+import gzip
 import io
+import json
 import os
 import pathlib
 import tarfile
 import textwrap
 import typing as t
+import urllib.parse
 
 try:
     import click
@@ -83,6 +87,24 @@ def find_build_configs() -> t.Iterator[pathlib.Path]:
         yield pathlib.Path(item)
 
 
+def build_ide_link(source_dir: pathlib.Path) -> str:
+    definition = _encode_link_part(source_dir / "definition.json")
+    input_schema = _encode_link_part(source_dir / "input_schema.json")
+    return (
+        "https://globus.github.io/flows-ide?format=gzip&"
+        f"d={definition}&s={input_schema}"
+    )
+
+
+def _encode_link_part(source_path: pathlib.Path) -> str:
+    # load and dump JSON to strip whitespace
+    loaded_doc = json.loads(source_path.read_bytes())
+    doc_bytes = json.dumps(loaded_doc, separators=(",", ":")).encode("utf-8")
+    gzipped_doc = gzip.compress(doc_bytes)
+    b64_gzipped_doc = base64.b64encode(gzipped_doc)
+    return urllib.parse.quote_from_bytes(b64_gzipped_doc.rstrip(b"="))
+
+
 def render_example_index_doc(
     source_dir: pathlib.Path, config: ExampleDocBuildConfig
 ) -> bytes:
@@ -103,23 +125,37 @@ def render_example_index_doc(
 
     if config.append_source_blocks:
         content = append_source_blocks(content)
-    content = prepend_preamble(config, content)
+
+    ide_link: str | None = None
+    if config.include_ide_link:
+        ide_link = build_ide_link(source_dir)
+
+    content = prepend_preamble(config, ide_link, content)
     return content
 
 
-def prepend_preamble(config: ExampleDocBuildConfig, content: bytes) -> bytes:
-    return (
-        textwrap.dedent(
-            f"""\
-            ---
-            menu_weight: {config.menu_weight}
-            ---
+def prepend_preamble(
+    config: ExampleDocBuildConfig, ide_link: str | None, content: bytes
+) -> bytes:
+    preamble = textwrap.dedent(
+        f"""\
+        ---
+        menu_weight: {config.menu_weight}
+        ---
 
-            """
-        ).encode("utf-8")
-        + content
+        """
     )
 
+    if ide_link is not None:
+        preamble += textwrap.dedent(
+            f"""
+            :flows_ide_link: {ide_link}
+
+            """
+        )
+
+    return preamble.encode("utf-8") + content
+
 
 def append_source_blocks(content: bytes) -> bytes:
     return (
@@ -208,6 +244,7 @@ class ExampleDocBuildConfig:
     index_source: IndexSourceConfig
     append_source_blocks: bool
     menu_weight: int
+    include_ide_link: bool
     include_files: list[str]
 
     @classmethod
@@ -220,6 +257,7 @@ def _load(cls, data: dict[str, t.Any]) -> t.Self:
             index_source=IndexSourceConfig._load(data["index_source"]),
             append_source_blocks=data["append_source_blocks"],
             menu_weight=data["menu_weight"],
+            include_ide_link=data.get("include_ide_link", True),
             # fill the default files to include if not present
             include_files=data.get(
                 "include_files",

support/doc_config_schema.json

@@ -30,6 +30,9 @@
     },
     "menu_weight": {
       "type": "integer"
+    },
+    "include_ide_link": {
+      "type": "boolean"
     }
   },
   "required": [

transfer_examples/looping_batched_move/README.adoc

@@ -1,5 +1,7 @@
 = Looping Batched Move
 
+link:{flows_ide_link}[Try it out in the Flows IDE.^]
+
 [TIP]
 =====
 This example is a demonstration of looping in a **flow**.

transfer_examples/move/README.adoc

@@ -1,5 +1,7 @@
 = Move (copy and delete) files
 
+link:{flows_ide_link}[Try it out in the Flows IDE.^]
+
 == Description
 
 Perform a 'move' operation on a directory by first transferring from a source to a destination and then deleting from the source.

transfer_examples/simple/README.adoc

@@ -1,5 +1,7 @@
 = Simple Transfer
 
+link:{flows_ide_link}[Try it out in the Flows IDE.^]
+
 == Description
 
 Do a single file or directory transfer with a 15 minute time limit.

transfer_examples/transfer_after_approval/README.adoc

@@ -1,5 +1,7 @@
 = Transfer After Approval
 
+link:{flows_ide_link}[Try it out in the Flows IDE.^]
+
 == Description
 
 Allow users to submit an approval request to transfer a file to a destination Guest Collection.

transfer_examples/transfer_share/README.adoc

@@ -1,5 +1,7 @@
 = Transfer and Share Files
 
+link:{flows_ide_link}[Try it out in the Flows IDE.^]
+
 == Description
 
 Move and share files by transferring them to a Guest Collection.

transfer_examples/two_hop/README.adoc

@@ -1,5 +1,7 @@
 = Two Stage Globus Transfer
 
+link:{flows_ide_link}[Try it out in the Flows IDE.^]
+
 == Description
 
 Transfer from source to intermediate and then from intermediate to destination.