README.md

@@ -1,3 +1,83 @@
-# Action-digikey-search-html-report-Demo
+# DigiKey-Search-HTML-Report AllSpice Actions Demo
+This is repository with an Altium-based design for demonstrating the "DigiKey Search HTML Report" AllSpice Actions add-on.
 
-A repository for demonstrating the "DigiKey Search HTML Report" AllSpice Actions add-on.
+This action uses the [generate-bom](https://hub.allspice.io/Actions/generate-bom) and [digikey-search-html-report](https://hub.allspice.io/Actions/digikey-search-html-report) Actions add-ons publically available in the [AllSpice Hub Actions](https://hub.allspice.io/Actions) organization.
+
+As shown and explained below in the YML workflow file, the generate-bom add-on is used to generate a BOM using the py-allspice BOM generation utility function, and the digikey-search-html-report add-on is used to search DigiKey for BOM line items using the DigiKey API.  See the [DigiKey API docs](https://developer.digikey.com/products) for more information.
+
+## Usage
+
+### Step 1) Add the DIGIKEY_CLIENT_ID and DIGIKEY_CLIENT_SECRET secrets to your repository.
+
+This add-on requires the DigiKey client ID and client secret to be stored as Actions secrets. Refer to the [knowledge base article on Actions secrets](https://learn.allspice.io/docs/secrets#actions-secrets) to learn how to add the required secrets to your repository.
+
+<img height="400" src="./images/repository_secrets.png">
+
+### Step 2) Add the following step to your actions:
+
+```yaml
+name: Generate DigiKey Report
+on:
+  push:
+  issues:
+    types: [opened, closed, reopened]
+
+jobs:
+  Generate_DigiKey_Report:
+    runs-on: ubuntu-latest
+    steps:
+      # Checkout is only needed if columns.json is committed in your Altium project repo.
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Generate BOM
+        uses: https://hub.allspice.io/Actions/generate-bom@v0.3
+        with:
+          # The path to the project file in your repo (.PrjPcb for Altium, .DSN for OrCad).
+          source_path: Archimajor.PrjPcb
+          # [optional] A path to a JSON file mapping columns to the component attributes
+          # they are from. This file must be provided.
+          # Default: 'columns.json'
+          columns: .allspice/columns.json
+          # [optional] The path to the output file that will be generated.
+          # Default: 'bom.csv'
+          output_file_name: bom.csv
+          # [optional] A comma-separated list of columns to group the BOM by. If empty
+          # or not present, the BOM will be flat.
+          # Default: ''
+          group_by: "Part Number"
+          # [optional] The variant of the project to generate the BOM for. If empty
+          # or not present, the BOM will be generated for the default variant.
+          # Default: ''
+          variant: ""
+
+      # Print bom.csv to terminal
+      - name: Show BOM
+        run: cat bom.csv
+
+      # Upload BOM as artifact
+      - name: Upload file as artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: BOM.csv
+          path: bom.csv
+
+      - name: Generate DigiKey Report
+        uses: https://hub.allspice.io/Actions/digikey-search-html-report.git@v1
+        with:
+          # The input BOM file for generating the DigiKey report
+          bom_file: bom.csv
+          # The DigiKey client ID
+          digikey_client_id: ${{ secrets.DIGIKEY_CLIENT_ID }}
+          # The DigiKey client secret
+          digikey_client_secret: ${{ secrets.DIGIKEY_CLIENT_SECRET }}
+
+      # Upload component report as artifact
+      - name: Upload component report as artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: DigiKey_Component_Report.zip
+          path: component_report.zip
+```
+
+Refer to the [generate-bom](https://hub.allspice.io/Actions/generate-bom) and [digikey-search-html-report](https://hub.allspice.io/Actions/digikey-search-html-report) add-on pages for usage and background on the add-ons used in this workflow demonstration.