Build links to the Flows IDE for rendered pages

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.