docs: update docs

jackdbd · Dec 27, 2022 · b5f921a · b5f921a
1 parent b03753b
commit b5f921a
Show file tree

Hide file tree

Showing 34 changed files with 129 additions and 105 deletions.
diff --git a/README.md b/README.md
@@ -26,18 +26,28 @@ npm install
 
 ## Build
 
-This monorepo uses [Typescript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) to build all of its libraries.
+This monorepo uses [Typescript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) to build all of its libraries, and [Turborepo](https://turbo.build/repo) for all other tasks.
 
 Build all libraries:
 
 ```sh
-npm run build
+npm run build:libs
 ```
 
-## Test
+Build all libraries and applications:
 
-Run all tests on all packages:
+```sh
+npm run build:apps
+```
+
+Build all docs:
+
+```sh
+npm run build:docs
+```
+
+Generate a file size report for each library:
 
 ```sh
-npm run test
+npm run size
 ```
diff --git a/docs/README.md b/docs/README.md
@@ -5,9 +5,10 @@ The **documentation** for each package is automatically generated by [TypeDoc](h
 
 The **API docs** are generated by [api-extractor](https://api-extractor.com/) + [api-documenter](https://api-extractor.com/pages/setup/generating_docs/).
 
-:warning: Do **not** edit this file manually. This file is generated by `docs-index.mjs` (see [scripts](https://github.com/jackdbd/matsuri/tree/main/scripts/README.md)).
+:warning: Do **not** edit this file manually. This file is generated by `docs-index.mjs` (see [scripts](https://github.com/jackdbd/matsuri/tree/canary/scripts/README.md)).
 
-- [hapi-healthcheck-plugin](./hapi-healthcheck-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/main/packages/hapi-healthcheck-plugin/api-docs/index.md))
-- [hapi-logger-plugin](./hapi-logger-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/main/packages/hapi-logger-plugin/api-docs/index.md))
-- [hapi-request-event-predicates](./hapi-request-event-predicates/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/main/packages/hapi-request-event-predicates/api-docs/index.md))
-- [hapi-telegram-plugin](./hapi-telegram-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/main/packages/hapi-telegram-plugin/api-docs/index.md))
+- [hapi-github-issue-plugin](./hapi-github-issue-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/canary/packages/hapi-github-issue-plugin/api-docs/index.md))
+- [hapi-healthcheck-plugin](./hapi-healthcheck-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/canary/packages/hapi-healthcheck-plugin/api-docs/index.md))
+- [hapi-logger-plugin](./hapi-logger-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/canary/packages/hapi-logger-plugin/api-docs/index.md))
+- [hapi-request-event-predicates](./hapi-request-event-predicates/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/canary/packages/hapi-request-event-predicates/api-docs/index.md))
+- [hapi-telegram-plugin](./hapi-telegram-plugin/index.html) (and [API docs](https://github.com/jackdbd/matsuri/tree/canary/packages/hapi-telegram-plugin/api-docs/index.md))
diff --git a/docs/hapi-github-issue-plugin/assets/highlight.css b/docs/hapi-github-issue-plugin/assets/highlight.css
@@ -15,8 +15,6 @@
     --dark-hl-6: #4FC1FF;
     --light-hl-7: #098658;
     --dark-hl-7: #B5CEA8;
-    --light-hl-8: #0451A5;
-    --dark-hl-8: #9CDCFE;
     --light-code-background: #FFFFFF;
     --dark-code-background: #1E1E1E;
 }
@@ -30,7 +28,6 @@
     --hl-5: var(--light-hl-5);
     --hl-6: var(--light-hl-6);
     --hl-7: var(--light-hl-7);
-    --hl-8: var(--light-hl-8);
     --code-background: var(--light-code-background);
 } }
 
@@ -43,7 +40,6 @@
     --hl-5: var(--dark-hl-5);
     --hl-6: var(--dark-hl-6);
     --hl-7: var(--dark-hl-7);
-    --hl-8: var(--dark-hl-8);
     --code-background: var(--dark-code-background);
 } }
 
@@ -56,7 +52,6 @@
     --hl-5: var(--light-hl-5);
     --hl-6: var(--light-hl-6);
     --hl-7: var(--light-hl-7);
-    --hl-8: var(--light-hl-8);
     --code-background: var(--light-code-background);
 }
 
@@ -69,7 +64,6 @@
     --hl-5: var(--dark-hl-5);
     --hl-6: var(--dark-hl-6);
     --hl-7: var(--dark-hl-7);
-    --hl-8: var(--dark-hl-8);
     --code-background: var(--dark-code-background);
 }
 
@@ -81,5 +75,4 @@
 .hl-5 { color: var(--hl-5); }
 .hl-6 { color: var(--hl-6); }
 .hl-7 { color: var(--hl-7); }
-.hl-8 { color: var(--hl-8); }
 pre, code { background: var(--code-background); }
diff --git a/docs/hapi-github-issue-plugin/index.html b/docs/hapi-github-issue-plugin/index.html
@@ -16,7 +16,7 @@ <h1>@jackdbd/hapi-github-issue-plugin</h1>
 </a>
 <p><a href="https://badge.fury.io/js/@jackdbd%2Fhapi-github-issue-plugin"><img src="https://badge.fury.io/js/@jackdbd%2Fhapi-github-issue-plugin.svg" alt="npm version"></a>
 <img src="https://img.shields.io/snyk/vulnerabilities/npm/@jackdbd%2Fhapi-github-issue-plugin" alt="Snyk Vulnerabilities for npm package"></p>
-<p>Hapi plugin that...</p>
+<p>Hapi plugin that automatically creates a GitHub issue when a request matches one of the rules you defined.</p>
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 </details>
@@ -28,23 +28,46 @@ <h2>Installation</h2>
 <pre><code class="language-sh"><span class="hl-0">npm install @jackdbd/hapi-github-issue-plugin</span>
 </code></pre>
 
+<a href="#preliminary-operations" id="preliminary-operations" style="color: inherit; text-decoration: none;">
+  <h2>Preliminary Operations</h2>
+</a>
+
+<a href="#github-personal-access-token" id="github-personal-access-token" style="color: inherit; text-decoration: none;">
+  <h3>GitHub personal access token</h3>
+</a>
+<p>This Hapi plugin makes a POST request to <code>{{GitHub-API}}/repos/:owner/:repo/issues</code> whenever an HTTP request matches one of the predicates used to configure the plugin itself. To allow this plugin to create an issue in your GitHub repository, you need to configure it with a <a href="https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token">GitHub personal access token</a> with the required <a href="https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps">OAuth scopes</a>. You can reuse an existing personal access token, or create a new one.</p>
+<p><img src="../../assets/images/hapi-github-issue-plugin-oauth-scopes.png" alt="OAuth scopes for the hapi-github-issue-plugin"></p>
+
 <a href="#usage" id="usage" style="color: inherit; text-decoration: none;">
   <h2>Usage</h2>
 </a>
+<p>If you register this plugin without passing any options...</p>
 <pre><code class="language-ts"><span class="hl-1">import</span><span class="hl-0"> </span><span class="hl-2">githubIssue</span><span class="hl-0"> </span><span class="hl-1">from</span><span class="hl-0"> </span><span class="hl-3">&#39;@jackdbd/hapi-github-issue-plugin&#39;</span><br/><br/><span class="hl-1">export</span><span class="hl-0"> </span><span class="hl-4">const</span><span class="hl-0"> </span><span class="hl-5">app</span><span class="hl-0"> = </span><span class="hl-4">async</span><span class="hl-0"> (</span><span class="hl-2">config</span><span class="hl-0">) </span><span class="hl-4">=&gt;</span><span class="hl-0"> {</span><br/><br/><span class="hl-0">  </span><span class="hl-4">const</span><span class="hl-0"> </span><span class="hl-6">server</span><span class="hl-0"> = </span><span class="hl-2">Hapi</span><span class="hl-0">.</span><span class="hl-5">server</span><span class="hl-0">({ </span><span class="hl-2">port:</span><span class="hl-0"> </span><span class="hl-7">8080</span><span class="hl-0"> })</span><br/><br/><span class="hl-0">  </span><span class="hl-1">await</span><span class="hl-0"> </span><span class="hl-2">server</span><span class="hl-0">.</span><span class="hl-5">register</span><span class="hl-0">({ </span><span class="hl-2">plugin:</span><span class="hl-0"> </span><span class="hl-2">githubIssue</span><span class="hl-0"> })</span><br/><br/><span class="hl-0">  </span><span class="hl-1">return</span><span class="hl-0"> { </span><span class="hl-2">server</span><span class="hl-0"> }</span><br/><span class="hl-0">}</span>
 </code></pre>
+<p>...it will catch any internal server error and create a GitHub issue like this one:</p>
+<p><img src="../../assets/images/hapi-github-issue-plugin-internal-server-error.png" alt="Telegram message about an internal server error in your Hapi app"></p>
 
 <a href="#configuration" id="configuration" style="color: inherit; text-decoration: none;">
   <h2>Configuration</h2>
 </a>
-<p>TODO</p>
-<pre><code class="language-text">POST {{api}}/repos/:owner/:repo/issues
 
-:owner jackdbd
-:repo matsuri
-</code></pre>
-<pre><code class="language-json"><span class="hl-0">{</span><br/><span class="hl-0">  </span><span class="hl-8">&quot;title&quot;</span><span class="hl-0">: </span><span class="hl-3">&quot;Migrate to Turborepo&quot;</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-8">&quot;body&quot;</span><span class="hl-0">: </span><span class="hl-3">&quot;Follow [this guide](https://turbo.build/repo/docs/getting-started/add-to-project) to migrate.&quot;</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-8">&quot;assignees&quot;</span><span class="hl-0">: [</span><span class="hl-3">&quot;jackdbd&quot;</span><span class="hl-0">],</span><br/><span class="hl-0">  </span><span class="hl-8">&quot;milestone&quot;</span><span class="hl-0">: </span><span class="hl-4">null</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-8">&quot;labels&quot;</span><span class="hl-0">: [</span><br/><span class="hl-0">    </span><span class="hl-3">&quot;bug&quot;</span><br/><span class="hl-0">  ]</span><br/><span class="hl-0">}</span>
-</code></pre>
+<a href="#options" id="options" style="color: inherit; text-decoration: none;">
+  <h3>Options</h3>
+</a>
+<table>
+<thead>
+<tr>
+<th>Option</th>
+<th>Default</th>
+<th>Explanation</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>request_event_matchers</code></td>
+<td>see <code>defaultRequestEventMatchers()</code> in <a href="./src/register.ts">register.ts</a></td>
+<td>Each rule controls which request matches, and which <code>title</code>, <code>body</code>, <code>assignees</code>, <code>milestone</code>, <code>labels</code> to use when creating the GitHub issue.</td>
+</tr>
+</tbody></table>
 </div></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">

diff --git a/docs/hapi-github-issue-plugin/interfaces/GitHubIssue.html b/docs/hapi-github-issue-plugin/interfaces/GitHubIssue.html
@@ -18,7 +18,7 @@ <h4>Hierarchy</h4>
 <ul class="tsd-hierarchy">
 <li><span class="target">GitHubIssue</span></li></ul></section><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/94a7dc1/packages/hapi-github-issue-plugin/src/interfaces.ts#L9">hapi-github-issue-plugin/src/interfaces.ts:9</a></li></ul></aside>
+<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/b03753b/packages/hapi-github-issue-plugin/src/interfaces.ts#L9">hapi-github-issue-plugin/src/interfaces.ts:9</a></li></ul></aside>
 <section class="tsd-panel-group tsd-index-group">
 <section class="tsd-panel tsd-index-panel">
 <details class="tsd-index-content tsd-index-accordion" open><summary class="tsd-accordion-summary tsd-index-summary">
@@ -38,27 +38,27 @@ <h2>Properties</h2>
 <h3 class="tsd-anchor-link"><code class="tsd-tag ts-flagOptional">Optional</code> <span>assignees</span><a href="#assignees" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none" id="icon-anchor-a"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5" id="icon-anchor-b"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5" id="icon-anchor-c"></path></svg></a></h3>
 <div class="tsd-signature">assignees<span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">[]</span></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/94a7dc1/packages/hapi-github-issue-plugin/src/interfaces.ts#L12">hapi-github-issue-plugin/src/interfaces.ts:12</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/b03753b/packages/hapi-github-issue-plugin/src/interfaces.ts#L12">hapi-github-issue-plugin/src/interfaces.ts:12</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface"><a id="body" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>body</span><a href="#body" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><use href="#icon-anchor-a"></use><use href="#icon-anchor-b"></use><use href="#icon-anchor-c"></use></svg></a></h3>
 <div class="tsd-signature">body<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/94a7dc1/packages/hapi-github-issue-plugin/src/interfaces.ts#L11">hapi-github-issue-plugin/src/interfaces.ts:11</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/b03753b/packages/hapi-github-issue-plugin/src/interfaces.ts#L11">hapi-github-issue-plugin/src/interfaces.ts:11</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface"><a id="labels" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><code class="tsd-tag ts-flagOptional">Optional</code> <span>labels</span><a href="#labels" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><use href="#icon-anchor-a"></use><use href="#icon-anchor-b"></use><use href="#icon-anchor-c"></use></svg></a></h3>
 <div class="tsd-signature">labels<span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">[]</span></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/94a7dc1/packages/hapi-github-issue-plugin/src/interfaces.ts#L14">hapi-github-issue-plugin/src/interfaces.ts:14</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/b03753b/packages/hapi-github-issue-plugin/src/interfaces.ts#L14">hapi-github-issue-plugin/src/interfaces.ts:14</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface"><a id="milestone" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><code class="tsd-tag ts-flagOptional">Optional</code> <span>milestone</span><a href="#milestone" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><use href="#icon-anchor-a"></use><use href="#icon-anchor-b"></use><use href="#icon-anchor-c"></use></svg></a></h3>
 <div class="tsd-signature">milestone<span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">number</span></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/94a7dc1/packages/hapi-github-issue-plugin/src/interfaces.ts#L13">hapi-github-issue-plugin/src/interfaces.ts:13</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/b03753b/packages/hapi-github-issue-plugin/src/interfaces.ts#L13">hapi-github-issue-plugin/src/interfaces.ts:13</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface"><a id="title" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>title</span><a href="#title" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><use href="#icon-anchor-a"></use><use href="#icon-anchor-b"></use><use href="#icon-anchor-c"></use></svg></a></h3>
 <div class="tsd-signature">title<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/94a7dc1/packages/hapi-github-issue-plugin/src/interfaces.ts#L10">hapi-github-issue-plugin/src/interfaces.ts:10</a></li></ul></aside></section></section></div>
+<li>Defined in <a href="https://github.com/jackdbd/matsuri/blob/b03753b/packages/hapi-github-issue-plugin/src/interfaces.ts#L10">hapi-github-issue-plugin/src/interfaces.ts:10</a></li></ul></aside></section></section></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">