From bc68ce94eab9dc0d0626079de8f894cddcc4ec40 Mon Sep 17 00:00:00 2001
From: James Renaud <29545188+jamesrenaud@users.noreply.github.com>
Date: Wed, 20 Dec 2023 03:12:17 -0500
Subject: [PATCH] chore(docs): add missing job summary documentation (#1574)

Co-authored-by: Konrad Pabjan <konradpabjan@github.com>
---
 packages/core/README.md | 126 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)

diff --git a/packages/core/README.md b/packages/core/README.md
index 35bd72db..ac8ced92 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -358,3 +358,129 @@ const {
   version, // 10.0.22621
 } = await platform.getDetails()
 ```
+
+#### Populating job summary
+
+These methods can be used to populate a [job summary](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary). A job summary is a buffer that can be added to throughout your job via `core.summary` methods.
+
+Job summaries when complete must be written to the summary buffer file via the `core.summary.write()` method.
+
+All methods except `addRaw()` utilize the `addRaw()` method to append to the buffer, followed by an EOL using the `addEOL()` method.
+
+```typescript
+
+// Write raw text, optionally add an EOL after the content, defaults to false
+core.summary.addRaw('Some content here :speech_balloon:', true)
+// Output: Some content here :speech_balloon:\n
+
+// Add an operating system-specific end-of-line marker
+core.summary.addEOL()
+// Output (POSIX): \n
+// Output (Windows): \r\n
+
+// Add a codeblock with an optional language for syntax highlighting
+core.summary.addCodeBlock('console.log(\'hello world\')', 'javascript')
+// Output: <pre lang="javascript"><code>console.log('hello world')</code></pre>
+
+// Add a list, second parameter indicates if list is ordered, defaults to false
+core.summary.addList(['item1','item2','item3'], true)
+// Output: <ol><li>item1</li><li>item2</li><li>item3</li></ol>
+
+// Add a collapsible HTML details element
+core.summary.addDetails('Label', 'Some detail that will be collapsed')
+// Output: <details><summary>Label</summary>Some detail that will be collapsed</details>
+
+// Add an image, image options parameter is optional, you can supply one of or both width and height in pixels
+core.summary.addImage('example.png', 'alt description of img', {width: '100', height: '100'})
+// Output: <img src="example.png" alt="alt description of img" width="100" height="100">
+
+// Add an HTML section heading element, optionally pass a level that translates to 'hX' ie. h2. Defaults to h1
+core.summary.addHeading('My Heading', '2')
+// Output: <h2>My Heading</h2>
+
+// Add an HTML thematic break <hr>
+core.summary.addSeparator()
+// Output: <hr>
+
+// Add an HTML line break <br>
+core.summary.addBreak()
+// Output: <br>
+
+// Add an HTML blockquote with an optional citation
+core.summary.addQuote('To be or not to be', 'Shakespeare')
+// Output: <blockquote cite="Shakespeare">To be or not to be</blockquote>
+
+// Add an HTML anchor tag
+core.summary.addLink('click here', 'https://github.com')
+// Output: <a href="https://github.com">click here</a>
+
+```
+
+Tables are added using the `addTable()` method, and an array of `SummaryTableRow`.
+
+```typescript
+
+export type SummaryTableRow = (SummaryTableCell | string)[]
+
+export interface SummaryTableCell {
+  /**
+   * Cell content
+   */
+  data: string
+  /**
+   * Render cell as header
+   * (optional) default: false
+   */
+  header?: boolean
+  /**
+   * Number of columns the cell extends
+   * (optional) default: '1'
+   */
+  colspan?: string
+  /**
+   * Number of rows the cell extends
+   * (optional) default: '1'
+   */
+  rowspan?: string
+}
+
+```
+
+For example
+
+```typescript
+
+const tableData = [
+  {data: 'Header1', header: true},
+  {data: 'Header2', header: true},
+  {data: 'Header3', header: true},
+  {data: 'MyData1'},
+  {data: 'MyData2'},
+  {data: 'MyData3'}
+]
+
+// Add an HTML table
+core.summary.addTable([tableData])
+// Output: <table><tr><th>Header1</th><th>Header2</th><th>Header3</th></tr><tr></tr><td>MyData1</td><td>MyData2</td><td>MyData3</td></tr></table>
+
+```
+
+In addition to job summary content, there are utility functions for interfacing with the buffer.
+
+```typescript
+
+// Empties the summary buffer AND wipes the summary file on disk
+core.summary.clear()
+
+// Returns the current summary buffer as a string
+core.summary.stringify()
+
+// If the summary buffer is empty
+core.summary.isEmptyBuffer()
+
+// Resets the summary buffer without writing to the summary file on disk
+core.summary.emptyBuffer()
+
+// Writes text in the buffer to the summary buffer file and empties the buffer, optionally overwriting all existing content in the summary file with buffer contents. Defaults to false.
+core.summary.write({overwrite: true})
+```
\ No newline at end of file