Show Docs site with links directly to changed files (#1078)

Author: fundthmcalculus

.github/workflows/test-docs.yml

@@ -11,6 +11,7 @@ jobs:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 0  # Get everything so that the `mkdocs-git-authors` plugin answers correctly
+          ref: ${{ github.head_ref }}
       - uses: actions/setup-node@v3
         name: Setup Node v18
         with:
@@ -60,10 +61,14 @@ jobs:
         run: |
           echo "Deploying site ${{ env.DOCS_BRANCH_NAME }}"
           netlify deploy --site "${{ env.DOCS_BRANCH_NAME }}" --dir ./ --prod
+      - name: Get Changed Docs
+        id: docsite
+        run: |
+          python ./devops/build_sdks.py --language=docs_pr_automation --docs-branch-name=${{ env.DOCS_BRANCH_NAME }}
       - uses: mshick/add-pr-comment@v1
         with:
           message: |
-            [Preview docs site for ${{ github.head_ref }}@${{ github.sha }}](https://${{ env.DOCS_BRANCH_NAME }}.netlify.app/)
+            ${{ steps.docsite.outputs.netlify_comment }}
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           repo-token-user-login: 'github-actions[bot]'
           allow-repeats: false

devops/build_sdks.py

@@ -8,14 +8,12 @@
 import platform
 import shutil
 import subprocess
+
+import pygit2
+import requests
 from os.path import join, abspath, dirname, isdir, split
 from typing import Dict
-
-try:
-    import requests
-except:
-    os.system("pip install requests")
-    import requests
+from pygit2 import Repository
 
 
 def parse_version_tag():
@@ -97,7 +95,8 @@ def get_language_dir(language_name: str) -> str:
     return abspath(join(dirname(abspath(__file__)), "..", language_name))
 
 
-def get_sdk_dir() -> str:
+@property
+def sdk_dir() -> str:
     """Get the full path of the root of the sdk repository"""
     return abspath(join(dirname(abspath(__file__)), ".."))
 
@@ -125,7 +124,9 @@ def build_java(args) -> None:
     )
     update_line(
         join(java_dir, "src", "main", "java", "trinsic", "TrinsicUtilities.java"),
-        {"final String sdkVersion = ": f'    final String sdkVersion = "{get_package_versions(args)}";'},
+        {
+            "final String sdkVersion = ": f'    final String sdkVersion = "{get_package_versions(args)}";'
+        },
     )
     copy_okapi_libs(abspath(join(java_dir, "..", "libs")))
 
@@ -148,7 +149,9 @@ def build_golang(args) -> None:
     golang_dir = abspath(join(get_language_dir("go"), "services"))
     update_line(
         join(golang_dir, "services.go"),
-        {"const sdkVersion = ": f'    const sdkVersion = "{get_package_versions(args)}"'},
+        {
+            "const sdkVersion = ": f'    const sdkVersion = "{get_package_versions(args)}"'
+        },
     )
     # Copy in the binaries
     copy_okapi_libs(golang_dir, "windows-gnu")
@@ -195,7 +198,7 @@ def build_java_docs(args):
     # npm ci in the root of sdk
     subprocess.Popen(
         r"node ./node_modules/groovydoc-to-markdown/src/doc2md.js  ./java java ./docs/reference/java",
-        cwd=get_sdk_dir(),
+        cwd=sdk_dir(),
     ).wait()
 
 
@@ -204,10 +207,10 @@ def build_dotnet_docs(args) -> None:
     # dotnet tool install DefaultDocumentation.Console -g
     assembly_file = "./dotnet/Trinsic/bin/Debug/net6.0/Trinsic.dll"
     output_doc_folder = "./docs/reference/dotnet"
-    clean_dir(abspath(join(get_sdk_dir(), output_doc_folder)))
+    clean_dir(abspath(join(sdk_dir(), output_doc_folder)))
     subprocess.Popen(
         f"defaultdocumentation --AssemblyFilePath {assembly_file} --OutputDirectoryPath {output_doc_folder} --FileNameMode Name --GeneratedPages Namespaces",
-        cwd=get_sdk_dir(),
+        cwd=sdk_dir(),
     ).wait()
 
 
@@ -238,6 +241,46 @@ def build_docs(args):
     build_go_docs(args)
 
 
+def build_docs_site(args):
+    # git diff --name-only
+    proc = subprocess.run(
+        ["git", "diff", "origin/main", "--name-only"], capture_output=True, text=True
+    )
+    output = proc.stdout.split("\n")
+    # Skip the warning about line feed
+    output = [
+        line
+        for line in output
+        if not line.lower().startswith("warning:")
+           and not line.lower().startswith("the file will have its")
+           and line
+    ]
+    # Get only markdown files
+    output = [line for line in output if line.lower().endswith(".md")]
+
+    proc = subprocess.run(["git", "rev-parse", "--short", "HEAD"], capture_output=True, text=True)
+    github_sha = proc.stdout.strip()
+    proc = subprocess.run(["git", "rev-parse", "--abbrev-ref", "HEAD"], capture_output=True, text=True)
+    github_head_ref = proc.stdout.strip()
+
+
+    # Export a markdown formatted list of changed pages
+    github_comment = [
+        f"[Preview docs site for {github_head_ref}@{github_sha}](https://{args.docs_branch_name}.netlify.app/)"
+    ]
+    github_comment.append("Changed paths:")
+    github_comment.extend(
+        [
+            f"{ij + 1}. [{md_file}](https://{args.docs_branch_name}.netlify.app/{md_file.replace('.md', '').replace('docs/', '')})"
+            for ij, md_file in enumerate(output)
+        ]
+    )
+    # TODO - maybe cap it if there are too many files to list?
+    # This is a github action newline escape
+    md_text = "%0A".join(github_comment)
+    print(f"::set-output name=netlify_comment::{md_text}")
+
+
 def build_none(args) -> None:
     """
     This is here, so you can specify no language to update - eg just download plugins
@@ -248,6 +291,7 @@ def build_none(args) -> None:
 def parse_arguments():
     parser = argparse.ArgumentParser(description="Process SDK building")
     parser.add_argument("--package-version", help="Manual override package version")
+    parser.add_argument("--docs-branch-name", help="docs branch name")
     parser.add_argument(
         "--language", help="Comma-separated languages to build", default="all"
     )
@@ -267,6 +311,7 @@ def main():
         "java": build_java,
         "dart": build_dart,
         "typescript": build_typescript,
+        "docs_pr_automation": build_docs_site,
         "none": build_none,
     }
     # If "all" is specified, set the array of languages to build to the list of all languages we _can_ build.

devops/generate_proto_files.py

@@ -185,7 +185,7 @@ def update_golang():
         'okapiproto "github.com/trinsic-id/sdk/go/okapiproto"': 'okapiproto "github.com/trinsic-id/okapi/go/okapiproto"',
         '_ "services/options"': '_ "github.com/trinsic-id/sdk/go/proto/services/options"',
         'account "services/account/v1/account"': 'account "github.com/trinsic-id/sdk/go/proto/services/account/v1/account"',
-        'common "services/common/v1/common"': 'account "github.com/trinsic-id/sdk/go/proto/services/common/v1/common"',
+        'common "services/common/v1/common"': 'common "github.com/trinsic-id/sdk/go/proto/services/common/v1/common"',
     }
     for file_name in glob.glob(join(go_proto_path, "**", "*.go"), recursive=True):
         update_line(file_name, replace_pairs)

devops/requirements.txt

@@ -1,4 +1,5 @@
 git+https://github.com/danielgtaylor/python-betterproto.git@3ca092a72494f9225bcb124aab2d0675f9e8c125#egg=betterproto[compiler]
 grpcio-tools
 requests
-markupsafe==2.1.1
+markupsafe==2.1.1
+pygit2

docs/go/index.md

@@ -22,4 +22,3 @@ Once the go package is installed and configured, you're ready to start building!
 
 [Start Walkthrough](../walkthroughs/vaccination.md){ .md-button .md-button--primary } [Explore API](../reference/index.md){ .md-button } [Go API Reference](../reference/index.md){ .md-button }
 
-

docs/java/index.md

@@ -1,6 +1,6 @@
-# The Trinsic Java SDK
+# The Trinsic Java / Kotlin SDK
 
-The Trinsic Java SDK makes it easy to interact with the Trinsic API from any Java application. The most recent version of the package is found on the [Github Release](https://github.com/trinsic-id/sdk/releases). You can find the SDKs source on [Github](https://github.com/trinsic-id/sdk/tree/main/java).
+The Trinsic Java / Kotlin SDK makes it easy to interact with the Trinsic API from any Java (or Kotlin) application. The most recent version of the package is found on the [Github Release](https://github.com/trinsic-id/sdk/releases). You can find the SDKs source on [Github](https://github.com/trinsic-id/sdk/tree/main/java).
 
 ## Installation
 1. Add the `urlFile` code shown below to your `build.gradle`.

docs/roadmap.md

@@ -7,8 +7,8 @@
 - [:material-language-python: Python](python/index.md)
 - [:fontawesome-brands-js-square: Web](web/index.md)
 - [:material-language-java: Java](java/index.md)
+- [:material-menu: Go](go/index.md)
+- [:material-language-ruby: Ruby](ruby/index.md)
 ### Coming Soon
 - :material-android: Android
 - :material-apple: iOS
-- :material-menu: Go
-- :material-language-ruby: Ruby

java/src/test/java/trinsic/ProviderServiceTest.java

@@ -1,75 +1,74 @@
 package trinsic;
 
-import com.google.protobuf.InvalidProtocolBufferException;
+import java.io.IOException;
+import java.util.concurrent.ExecutionException;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import trinsic.okapi.DidException;
 import trinsic.services.AccountService;
 import trinsic.services.ProviderService;
 import trinsic.services.TrinsicService;
-import trinsic.services.account.v1.LoginRequest;
 import trinsic.services.common.v1.SupportedDidMethod;
 import trinsic.services.provider.v1.*;
 
-import java.io.IOException;
-import java.util.concurrent.ExecutionException;
-
 public class ProviderServiceTest {
-    @Test
-    @Disabled
-    public void testProviderServiceInviteParticipant()
-        throws IOException, DidException, ExecutionException, InterruptedException {
-        var accountService = new AccountService(TrinsicUtilities.getTrinsicServiceOptions());
-        var account = accountService.signIn().get();
+  @Test
+  @Disabled
+  public void testProviderServiceInviteParticipant()
+      throws IOException, DidException, ExecutionException, InterruptedException {
+    var accountService = new AccountService(TrinsicUtilities.getTrinsicServiceOptions());
+    var account = accountService.signIn().get();
 
-        var providerService = new ProviderService(TrinsicUtilities.getTrinsicServiceOptions(account));
-        var ecosystem =
-            providerService
-                .createEcosystem(CreateEcosystemRequest.newBuilder().setName("Test Ecosystem").build())
-                .get();
-        var invitation =
-            InviteRequest.newBuilder()
-                .setParticipant(ParticipantType.participant_type_individual)
-                .setDescription("I dunno")
-                .build();
-        var response = providerService.invite(invitation).get();
-        Assertions.assertNotNull(response);
+    var providerService = new ProviderService(TrinsicUtilities.getTrinsicServiceOptions(account));
+    var ecosystem =
+        providerService
+            .createEcosystem(CreateEcosystemRequest.newBuilder().setName("Test Ecosystem").build())
+            .get();
+    var invitation =
+        InviteRequest.newBuilder()
+            .setParticipant(ParticipantType.participant_type_individual)
+            .setDescription("I dunno")
+            .build();
+    var response = providerService.invite(invitation).get();
+    Assertions.assertNotNull(response);
 
-        var status =
-            providerService
-                .invitationStatus(
-                    InvitationStatusRequest.newBuilder()
-                        .setInvitationId(response.getInvitationId())
-                        .build())
-                .get();
-        Assertions.assertNotNull(status);
-    }
+    var status =
+        providerService
+            .invitationStatus(
+                InvitationStatusRequest.newBuilder()
+                    .setInvitationId(response.getInvitationId())
+                    .build())
+            .get();
+    Assertions.assertNotNull(status);
+  }
 
-    @Test
-    public void testUpgradeDid() throws IOException, DidException, ExecutionException, InterruptedException {
-        var trinsic = new TrinsicService(TrinsicUtilities.getTrinsicServiceOptions());
+  @Test
+  public void testUpgradeDid()
+      throws IOException, DidException, ExecutionException, InterruptedException {
+    var trinsic = new TrinsicService(TrinsicUtilities.getTrinsicServiceOptions());
 
-        var ecoCreateResponse = trinsic.provider().createEcosystem(CreateEcosystemRequest.getDefaultInstance()).get();
+    var ecoCreateResponse =
+        trinsic.provider().createEcosystem(CreateEcosystemRequest.getDefaultInstance()).get();
 
-        var infoResponse = trinsic.account().info().get();
-        var walletId = infoResponse.getWalletId();
+    var infoResponse = trinsic.account().info().get();
+    var walletId = infoResponse.getWalletId();
 
-        // Wrap in try-catch as ecosystems cannot upgrade DIDs by default presently
-        try {
-            // upgradeDid() {
-            var upgradeRequest = UpgradeDidRequest.newBuilder()
-                .setWalletId(walletId)
-                .setMethod(SupportedDidMethod.ION)
-                .setIonOptions(IonOptions.newBuilder()
-                    .setNetwork(IonOptions.IonNetwork.TestNet)
-                    .build()
-                ).build();
+    // Wrap in try-catch as ecosystems cannot upgrade DIDs by default presently
+    try {
+      // upgradeDid() {
+      var upgradeRequest =
+          UpgradeDidRequest.newBuilder()
+              .setWalletId(walletId)
+              .setMethod(SupportedDidMethod.ION)
+              .setIonOptions(
+                  IonOptions.newBuilder().setNetwork(IonOptions.IonNetwork.TestNet).build())
+              .build();
 
-            var upgradeResponse = trinsic.provider().upgradeDID(upgradeRequest).get();
-            // }
-        } catch (Exception e) {
+      var upgradeResponse = trinsic.provider().upgradeDID(upgradeRequest).get();
+      // }
+    } catch (Exception e) {
 
-        }
     }
+  }
 }

java/src/test/java/trinsic/TrinsicServicesTest.java

@@ -3,16 +3,13 @@
 import java.io.IOException;
 import java.util.concurrent.ExecutionException;
 import org.junit.jupiter.api.Assertions;
-import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import trinsic.okapi.DidException;
 import trinsic.services.AccountService;
 import trinsic.services.ProviderService;
 import trinsic.services.account.v1.AccountInfoRequest;
-import trinsic.services.provider.v1.CreateEcosystemRequest;
 import trinsic.services.provider.v1.InvitationStatusRequest;
 import trinsic.services.provider.v1.InviteRequest;
-import trinsic.services.provider.v1.ParticipantType;
 
 class TrinsicServicesTest {
 

python/samples/provider_demo.py

@@ -84,9 +84,7 @@ async def provider_demo():
             request=UpgradeDidRequest(
                 wallet_id=wallet_id,
                 method=SupportedDidMethod.ION,
-                ion_options=IonOptions(
-                    network=IonOptionsIonNetwork.TestNet
-                )
+                ion_options=IonOptions(network=IonOptionsIonNetwork.TestNet),
             )
         )
         # }