Merge pull request #5 from globus/render-docs

Import doc site examples and setup rendering toolchain

Author: sirosen

.flake8

@@ -0,0 +1,4 @@
+[flake8]
+exclude = .git,.tox,__pycache__,.eggs,dist,.venv*,docs,build
+max-line-length = 88
+extend-ignore = W503,W504,E203

.github/workflows/release.yaml

@@ -0,0 +1,28 @@
+# build and release new docs as a release asset
+name: 📦 Package Docs
+on:
+  release:
+    types: [created]
+
+permissions:
+  contents: "write"
+
+jobs:
+  doc:
+    name: Bundle and Release Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
+        with:
+          python-version: "3.13"
+      - name: Install pipx
+        run: python -m pip install pipx
+      - name: Build the Doc Bundle
+        run: |
+          pipx run ./support/build-doc-bundle.py -o doc_bundle.tar.gz
+      # upload as a release asset
+      - name: Upload Doc Bundle
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "${{ github.ref_name }}" doc_bundle.tar.gz

.github/workflows/test.yaml

@@ -0,0 +1,26 @@
+name: "🧪 Test"
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+
+jobs:
+  test:
+    name: "${{ matrix.name }}"
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: "Test"
+            runner: "ubuntu-latest"
+            cpythons:
+              - "3.13"
+            tox-environments:
+              - "mypy"
+              - "build_doc_bundle"
+            cache-paths:
+              - ".mypy_cache/"
+    uses: "globus/workflows/.github/workflows/tox.yaml@f41714f6a8b102569807b348fce50960f9617df8" # v1.2
+    with:
+      config: "${{ toJSON(matrix) }}"

.pre-commit-config.yaml

@@ -22,7 +22,26 @@ repos:
       - id: codespell
         args: ["--ignore-regex", "https://[^\\s]*"]
 
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.33.0
+    hooks:
+      - id: check-github-workflows
+
   - repo: "https://github.com/sirosen/texthooks"
     rev: 0.6.8
     hooks:
       - id: alphabetize-codeowners
+
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 25.1.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.2.0
+    hooks:
+      - id: flake8
+        additional_dependencies:
+          - 'flake8-bugbear==24.12.12'
+          - 'flake8-comprehensions==3.16.0'
+          - 'flake8-typing-as-t==1.0.0'

compute_transfer_examples/register_compute_func.py

@@ -1,25 +1,30 @@
 #!/usr/bin/env python
 
+
 def do_tar(
     src_paths: list[str],
     dest_path: str,
     gcs_base_path: str = "/",
 ) -> str:
     """
-    Create a tar.gz archive from source files or directories and save it to the given destination.
+    Create a tar.gz archive from source files or directories and save it to the
+    given destination.
 
     Parameters:
         src_paths (list[str]):  Source paths of files or directories to be archived.
-        dest_path (str): Destination path where the tar.gz archive will be written. This can be either
-                         an existing directory or a file path (with the parent directory existing).
-        gcs_base_path (str): The shared GCS collection's configured base path. Default is "/".
+        dest_path (str): Destination path where the tar.gz archive will be
+                         written. This can be either an existing directory or a
+                         file path (with the parent directory existing).
+        gcs_base_path (str): The shared GCS collection's configured base path.
+                             Default is "/".
 
     Returns:
         str: The output tar archive file path.
 
     Raises:
-        ValueError: If src_paths is empty, dest_path is None, any provided path does not begin with the expected
-                    prefix, or if any source path or destination (or its parent) is invalid.
+        ValueError: If src_paths is empty, dest_path is None, any provided path
+                    does not begin with the expected prefix, or if any source
+                    path or destination (or its parent) is invalid.
         RuntimeError: If an error occurs during the creation of the tar archive.
 
     Example:
@@ -48,7 +53,8 @@ def transform_path_from_absolute(path: str) -> str:
         """Transform an absolute filesystem path back to a GCS-style path."""
         if not path.startswith(gcs_base_path):
             raise ValueError(
-                f"Path '{path}' does not start with the expected prefix '{gcs_base_path}'."
+                f"Path '{path}' does not start with "
+                f"the expected prefix '{gcs_base_path}'."
             )
         return path.replace(gcs_base_path, "/", 1)
 
@@ -72,7 +78,9 @@ def transform_path_from_absolute(path: str) -> str:
     # Validate transformed_dest_path
     if transformed_dest_path.exists():
         if not (transformed_dest_path.is_dir() or transformed_dest_path.is_file()):
-            raise ValueError(f"Destination path '{dest_path}' is neither a directory nor a file.")
+            raise ValueError(
+                f"Destination path '{dest_path}' is neither a directory nor a file."
+            )
     else:
         if not transformed_dest_path.parent.exists():
             raise ValueError(
@@ -95,7 +103,10 @@ def transform_path_from_absolute(path: str) -> str:
             transformed_dest_tar_path = transformed_dest_path.with_name(fn + ".tar.gz")
 
     # Informative message (could be replaced with logging.info in production code)
-    print(f"Creating tar file at {transformed_dest_tar_path.absolute()} with {len(transformed_src_paths)} source(s)")
+    print(
+        f"Creating tar file at {transformed_dest_tar_path.absolute()} "
+        f"with {len(transformed_src_paths)} source(s)"
+    )
 
     # Create the tar.gz archive with exception handling.
     try:
@@ -108,11 +119,16 @@ def transform_path_from_absolute(path: str) -> str:
             try:
                 transformed_dest_tar_path.unlink()
             except Exception as unlink_err:
-                print(f"Warning: Failed to remove incomplete tar file '{transformed_dest_tar_path}': {unlink_err}")
+                print(
+                    f"Warning: Failed to remove incomplete tar file "
+                    f"'{transformed_dest_tar_path}': {unlink_err}"
+                )
         raise RuntimeError(f"Failed to create tar archive: {e}") from e
 
     # Transform the output path back to a GCS-style path and return.
-    result_path = transform_path_from_absolute(str(transformed_dest_tar_path.absolute()))
+    result_path = transform_path_from_absolute(
+        str(transformed_dest_tar_path.absolute())
+    )
     return result_path
 
 

support/README.md

@@ -0,0 +1,3 @@
+# Support Tooling for Globus Flows Examples
+
+This directory contains internal tools for maintaining the example repository.