chore(docs): more details on usage and final results

krummbar · Jun 22, 2024 · 40e8883 · 40e8883
1 parent cce88e4
commit 40e8883
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 28 deletions.
diff --git a/README.adoc b/README.adoc
@@ -6,7 +6,6 @@
 // located in the /docs folder. The root file for the documentation is
 // /docs/index.adoc
 // ############################################################
-:source-highlighter: highlight.js
 :toc: macro
 :icons: font
 ifdef::env-github[]
@@ -32,28 +31,25 @@ This can be a subsequent step to {url-bruno-run-action}[bruno-run-action] to ren
 Supports bru run reports >= v1.20.0
 ====
 
-.TODO
-[NOTE]
-====
-Add example referenc
-====
+Examples of the final summary attached to the job can be found here:
+
+* xref:docs/examples/report-failure-result.md[]
+* xref:docs/examples/report-result.md[]
 
 toc::[]
 
 :leveloffset: 1
 
 = Usage
+:url-gha-continue-on-error: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error
 
-.TODO
-[NOTE]
-====
-Document usage
-====
+The listed example clones a repository source, executes the `bru run` command,
+and finally attaches a markdown summary at the end from the previous run.
 
 .Attach run summary
 [source,yaml]
 ----
-name: Bruno Test Collection
+name: Bruno Test & Report
 
 on:
   workflow_dispatch:
@@ -63,11 +59,30 @@ jobs:
     name: Bruno test collection
     runs-on: ubuntu-latest
     steps:
-      - name: Attach bru run summary
+      - name: Checkout  # <1>
+        id: checkout
+        uses: actions/checkout@v4
+
+      - name: Bruno CLI runner  # <2>
+        id: bru-cli
+        uses: krummbar/bruno-run-action@main
+        with:
+          path: bruno/api-it
+          output: bru-output.json # <3>
+          outputFormat: json
+
+      - name: Attach bru run summary # <4>
         uses: krummbar/bruno-run-report@main
+        continue-on-error: true # <5>
         with:
-          run-report-path: bru-output.json
+          run-report-path: bru-output.json # <6>
 ----
+<1> Clone repository
+<2> Execute `bru run` with a collection located in folder `bruno/api-it`
+<3> Specify the report result summary in *JSON* format
+<4> Generates the Markdown summary and attaches it to `${GITHUB_SUMMARY}`
+<5> *Optional* make report step succeed even though report step potentially fails, {url-gha-continue-on-error}[see documentation]
+<6> Needs to match the path from `3`
 
 == Inputs
 

diff --git a/docs/examples/usage.yaml b/docs/examples/usage.yaml
@@ -1,4 +1,4 @@
-name: Bruno Test Collection
+name: Bruno Test & Report
 
 on:
   workflow_dispatch:
@@ -8,7 +8,20 @@ jobs:
     name: Bruno test collection
     runs-on: ubuntu-latest
     steps:
-      - name: Attach bru run summary
+      - name: Checkout  # <1>
+        id: checkout
+        uses: actions/checkout@v4
+
+      - name: Bruno CLI runner  # <2>
+        id: bru-cli
+        uses: krummbar/bruno-run-action@main
+        with:
+          path: bruno/api-it
+          output: bru-output.json # <3>
+          outputFormat: json
+
+      - name: Attach bru run summary # <4>
         uses: krummbar/bruno-run-report@main
+        continue-on-error: true # <5>
         with:
-          run-report-path: bru-output.json
+          run-report-path: bru-output.json # <6>
diff --git a/docs/index.adoc b/docs/index.adoc
@@ -1,6 +1,5 @@
 = Bruno Run Report
 include::edit-advise.adoc[]
-:source-highlighter: highlight.js
 :toc: macro
 :icons: font
 ifdef::env-github[]
@@ -26,11 +25,10 @@ This can be a subsequent step to {url-bruno-run-action}[bruno-run-action] to ren
 Supports bru run reports >= v1.20.0
 ====
 
-.TODO
-[NOTE]
-====
-Add example referenc
-====
+Examples of the final summary attached to the job can be found here:
+
+* xref:docs/examples/report-failure-result.md[]
+* xref:docs/examples/report-result.md[]
 
 toc::[]
 

diff --git a/docs/usage.adoc b/docs/usage.adoc
@@ -1,16 +1,20 @@
 = Usage
+:url-gha-continue-on-error: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error
 
-.TODO
-[NOTE]
-====
-Document usage
-====
+The listed example clones a repository source, executes the `bru run` command,
+and finally attaches a markdown summary at the end from the previous run.
 
 .Attach run summary
 [source,yaml]
 ----
 include::examples/usage.yaml[]
 ----
+<1> Clone repository
+<2> Execute `bru run` with a collection located in folder `bruno/api-it`
+<3> Specify the report result summary in *JSON* format
+<4> Generates the Markdown summary and attaches it to `${GITHUB_SUMMARY}`
+<5> *Optional* make report step succeed even though report step potentially fails, {url-gha-continue-on-error}[see documentation]
+<6> Needs to match the path from `3`
 
 == Inputs