From a22c93cceb12520775d3695cdabd5fed9c19818f Mon Sep 17 00:00:00 2001
From: lowlighter <22963968+lowlighter@users.noreply.github.com>
Date: Sat, 15 Jan 2022 22:36:25 -0500
Subject: [PATCH] doc(plugins/notable): update

---
 source/plugins/notable/README.md    | 69 ++++++++++++++++++-----------
 source/plugins/notable/metadata.yml | 39 +++++++++-------
 2 files changed, 65 insertions(+), 43 deletions(-)

diff --git a/source/plugins/notable/README.md b/source/plugins/notable/README.md
index ff2d833a..80541e91 100644
--- a/source/plugins/notable/README.md
+++ b/source/plugins/notable/README.md
@@ -1,27 +1,29 @@
-### 🎩 Notable contributions
-
-The *notable* plugin displays badges of organization where you commited at least once on main branch.
-
+<!--header-->
 <table>
-  <td align="center">
-    <details open><summary>Indepth analysis</summary>
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.notable.indepth.svg">
-    </details>
-    <details><summary>Contributions in organizations only</summary>
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.notable.svg">
-    </details>
-    <img width="900" height="1" alt="">
-  </td>
+  <tr><th colspan="2"><h3>🎩 Notable contributions</h3></th></tr>
+  <tr><td colspan="2" align="center"><p>This plugin displays badges of repositories where you commited at least once on default branch.</p>
+</td></tr>
+  <tr>
+    <th rowspan="3">Supported features<br><sub><a href="metadata.yml">→ Full specification</a></sub></th>
+    <td><a href="/source/templates/classic"><code>📗 Classic template</code></a></td>
+  </tr>
+  <tr>
+    <td><code>👤 Users</code></td>
+  </tr>
+  <tr>
+    <td><code>🔑 (scopeless)</code> <code>read:org (optional)</code> <code>read:user (optional)</code> <code>repo (optional)</code></td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center">
+      <details open><summary>Indepth analysis</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.notable.indepth.svg" alt=""></img></details>
+      <details><summary>Contributions in organizations only</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.notable.svg" alt=""></img></details>
+      <img width="900" height="1" alt="">
+    </td>
+  </tr>
 </table>
+<!--/header-->
 
-#### Using `indepth` statistics
-
-The `plugin_notable_indepth` option lets you get additional metrics about your contribution, such as:
-- Total number of commits within a repository or organization. The badge will have a circular gauge which is proportional to the percentage of total contribution. It will also determine the resulting color of the badge.
-
-> 🔣 On web instances, `indepth` is an extra feature and must be enabled globally in `settings.json`
-
-#### ➡️ Available options
+## ➡️ Available options
 
 <!--options-->
 <table>
@@ -30,7 +32,7 @@ The `plugin_notable_indepth` option lets you get additional metrics about your c
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_notable</code></td>
-    <td rowspan="2"><p>Display notable contributions in organizations</p>
+    <td rowspan="2"><p>Enable notable plugin</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -41,6 +43,8 @@ The `plugin_notable_indepth` option lets you get additional metrics about your c
   <tr>
     <td nowrap="nowrap"><code>plugin_notable_filter</code></td>
     <td rowspan="2"><p>Query filter</p>
+<p>Based on <a href="https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax">GitHub search syntax</a>.
+Supported fields are <code>stars</code>, <code>forks</code> and <code>watchers</code></p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -49,7 +53,12 @@ The `plugin_notable_indepth` option lets you get additional metrics about your c
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_notable_from</code></td>
-    <td rowspan="2"><p>Filter by repository host account type</p>
+    <td rowspan="2"><p>Filter by repository owner account type</p>
+<ul>
+<li><code>all</code>: no filtering</li>
+<li><code>organization</code>: only organization accounts repositories</li>
+<li><code>user</code>: only user accounts repositories</li>
+</ul>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -60,7 +69,8 @@ The `plugin_notable_indepth` option lets you get additional metrics about your c
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_notable_repositories</code></td>
-    <td rowspan="2"><p>Also display repository name</p>
+    <td rowspan="2"><p>Toggle repository name display</p>
+<p>Note that Repositories hosted by user account will always be fully displayed</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -70,7 +80,7 @@ The `plugin_notable_indepth` option lets you get additional metrics about your c
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_notable_indepth</code></td>
-    <td rowspan="2"><p>Indepth notable contributions processing</p>
+    <td rowspan="2"><p>Indepth mode</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -82,9 +92,14 @@ The `plugin_notable_indepth` option lets you get additional metrics about your c
 </table>
 <!--/options-->
 
-*[→ Full specification](metadata.yml)*
+## 🔎 `indepth` mode
 
-#### ℹ️ Examples workflows
+The `plugin_notable_indepth` option collects additional stats about your contributions, such as:
+- Total number of commits within a repository or organization.
+
+For each of the above, a badge is awarded. Its color and progress depends of the associated value.
+
+## ℹ️ Examples workflows
 
 <!--examples-->
 ```yaml
diff --git a/source/plugins/notable/metadata.yml b/source/plugins/notable/metadata.yml
index 64904b03..c6315055 100644
--- a/source/plugins/notable/metadata.yml
+++ b/source/plugins/notable/metadata.yml
@@ -1,5 +1,9 @@
 name: "🎩 Notable contributions"
 category: github
+description: This plugin displays badges of repositories where you commited at least once on default branch.
+examples:
+  +indepth analysis: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.notable.indepth.svg
+  contributions in organizations only: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.notable.svg
 index: 15
 supports:
   - user
@@ -7,41 +11,44 @@ scopes:
   - public_access
 inputs:
 
-  # Enable or disable plugin
   plugin_notable:
-    description: Display notable contributions in organizations
+    description: Enable notable plugin
     type: boolean
     default: no
 
-  # Query filter
-  # Based on GitHub search notation
-  # Supported fields are "stars", "forks" and "watchers"
   plugin_notable_filter:
-    description: Query filter
+    description: |
+      Query filter
+
+      Based on [GitHub search syntax](https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax).
+      Supported fields are `stars`, `forks` and `watchers`
     type: string
     default: ""
     example: stars:>500 forks:>100
 
-  # Filter repositories depending on which type of account it is hosted
   plugin_notable_from:
-    description: Filter by repository host account type
+    description: |
+      Filter by repository owner account type
+      - `all`: no filtering
+      - `organization`: only organization accounts repositories
+      - `user`: only user accounts repositories
     type: string
     default: organization
     values:
-      - all           #
-      - organization  # Only hosted by organization accounts
-      - user          # Only hosted by user accounts
+      - all
+      - organization
+      - user
 
-  # Also display repository name along with organization name
-  # Note that repositories hosted by user account will always be displayed fully
   plugin_notable_repositories:
-    description: Also display repository name
+    description: |
+      Toggle repository name display
+
+      Note that Repositories hosted by user account will always be fully displayed
     type: boolean
     default: no
 
-  # Compute notable contributions with measured impact
   plugin_notable_indepth:
-    description: Indepth notable contributions processing
+    description: Indepth mode
     type: boolean
     default: no
     extras: yes