From ac2618d15765e979466549fc3262d0f188b42933 Mon Sep 17 00:00:00 2001
From: lowlighter <22963968+lowlighter@users.noreply.github.com>
Date: Sat, 15 Jan 2022 21:20:11 -0500
Subject: [PATCH] doc(plugins/projects): update

---
 source/plugins/projects/README.md    | 110 +++++++++++++++------------
 source/plugins/projects/metadata.yml |  28 +++----
 2 files changed, 77 insertions(+), 61 deletions(-)

diff --git a/source/plugins/projects/README.md b/source/plugins/projects/README.md
index 472eb409..0480468b 100644
--- a/source/plugins/projects/README.md
+++ b/source/plugins/projects/README.md
@@ -1,46 +1,28 @@
-### 🗂️ Active projects
-
-> ⚠️ This plugin requires a personal token with public_repo scope.
-
-The *projects* plugin displays the progress of your profile projects.
-
+<!--header-->
 <table>
-  <td align="center">
-    <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.projects.svg">
-    <img width="900" height="1" alt="">
-  </td>
+  <tr><th colspan="2"><h3>🗂️ Active projects</h3></th></tr>
+  <tr><td colspan="2" align="center"><p>This plugin displays progress of your profile and repository projects.</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> <a href="/source/templates/repository"><code>📘 Repository template</code></a></td>
+  </tr>
+  <tr>
+    <td><code>👤 Users</code> <code>👥 Organizations</code> <code>📓 Repositories</code></td>
+  </tr>
+  <tr>
+    <td><code>🔑 (scopeless)</code> <code>🔑 public_repo</code> <code>read:org (optional)</code> <code>read:user (optional)</code> <code>repo (optional)</code></td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center">
+      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.projects.svg" alt=""></img>
+      <img width="900" height="1" alt="">
+    </td>
+  </tr>
 </table>
+<!--/header-->
 
-Because of GitHub REST API limitation, provided token requires `public_repo` scope to access projects informations.
-
-Note that by default, projects have progress tracking disabled.
-To enable it, open the `≡ Menu` and edit the project to opt-in to `Track project progress` (it can be a bit confusing since it's actually not in the project settings).
-
-![Enable "Track project progress"](/.github/readme/imgs/plugin_projects_track_progress.png)
-
-<details>
-<summary>💬 Create a personal project on GitHub</summary>
-
-On your profile, select the `Projects` tab:
-![Create a new project](/.github/readme/imgs/plugin_projects_create.png)
-
-Fill the informations and set visibility to *public*:
-![Configure project](/.github/readme/imgs/plugin_projects_setup.png)
-
-</details>
-
-<details>
-<summary>💬 Use repositories projects</summary>
-
-It is possible to display projects related to repositories along with personal projects.
-
-To do so, open your repository project and retrieve the last URL endpoint, in the format `:user/:repository/projects/:project_id` (for example, `lowlighter/metrics/projects/1`) and add it in the `plugin_projects_repositories` option. Enable `Track project progress` in the project settings to display a progress bar in generated metrics.
-
-![Add a repository project](/.github/readme/imgs/plugin_projects_repositories.png)
-
-</details>
-
-#### ➡️ Available options
+## ➡️ Available options
 
 <!--options-->
 <table>
@@ -49,7 +31,7 @@ To do so, open your repository project and retrieve the last URL endpoint, in th
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_projects</code></td>
-    <td rowspan="2"><p>Display active projects</p>
+    <td rowspan="2"><p>Enable projects plugin</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -59,7 +41,8 @@ To do so, open your repository project and retrieve the last URL endpoint, in th
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_projects_limit</code></td>
-    <td rowspan="2"><p>Maximum number of projects to display</p>
+    <td rowspan="2"><p>Display limit</p>
+<p>Note that <code>plugin_projects_repositories</code> is not affected by this option</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -72,7 +55,8 @@ To do so, open your repository project and retrieve the last URL endpoint, in th
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_projects_repositories</code></td>
-    <td rowspan="2"><p>List of repository project identifiers to disaplay</p>
+    <td rowspan="2"><p>List of repositories projects</p>
+<p>Use the following syntax for each project <code>:user/:repo/projects/:project_id</code></p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -82,7 +66,7 @@ To do so, open your repository project and retrieve the last URL endpoint, in th
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_projects_descriptions</code></td>
-    <td rowspan="2"><p>Display projects descriptions</p>
+    <td rowspan="2"><p>Toggle projects descriptions display</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -93,9 +77,41 @@ To do so, open your repository project and retrieve the last URL endpoint, in th
 </table>
 <!--/options-->
 
-*[→ Full specification](metadata.yml)*
+## 🔄 Enabling progress tracking
 
-#### ℹ️ Examples workflows
+By default, projects have progress tracking disabled.
+
+To enable it, open the `≡ Menu` from the project page and opt-in to `Track project progress`.
+
+![Enable "Track project progress"](/.github/readme/imgs/plugin_projects_track_progress.png)
+
+## 👤 Use personal projects
+
+To create a personal project, select the `Projects` tab from your profile:
+![Create a new project](/.github/readme/imgs/plugin_projects_create.png)
+
+Fill informations and set visibility to *public*:
+![Configure project](/.github/readme/imgs/plugin_projects_setup.png)
+
+## 📓 Use repositories projects
+
+Repositories projects are created from the `Projects` tab of a repository.
+
+To use it with this plugin, retrieve the last section of the project URL (it should match the format `:user/:repository/projects/:project_id`) and add it in the `plugin_projects_repositories`.
+
+Be sure to tick `Track project progress` in project settings to display a progress bar.
+
+![Add a repository project](/.github/readme/imgs/plugin_projects_repositories.png)
+
+*Example: include a project repository*
+```yml
+- uses: lowlighter/metrics@latest
+  with:
+    plugin_projects: yes
+    plugin_projects_repositories: lowlighter/metrics/projects/1
+```
+
+## ℹ️ Examples workflows
 
 <!--examples-->
 ```yaml
@@ -110,4 +126,4 @@ with:
   plugin_projects_descriptions: 'yes'
 
 ```
-<!--/examples-->
\ No newline at end of file
+<!--/examples-->
diff --git a/source/plugins/projects/metadata.yml b/source/plugins/projects/metadata.yml
index a9ae7d54..6f7a87a6 100644
--- a/source/plugins/projects/metadata.yml
+++ b/source/plugins/projects/metadata.yml
@@ -1,5 +1,8 @@
 name: "🗂️ Active projects"
 category: github
+description: This plugin displays progress of your profile and repository projects.
+examples:
+  default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.projects.svg
 index: 11
 supports:
   - user
@@ -10,35 +13,32 @@ scopes:
   - public_repo
 inputs:
 
-  # Enable or disable plugin
   plugin_projects:
-    description: Display active projects
+    description: Enable projects plugin
     type: boolean
     default: no
 
-  # Number of projects to display
-  # Set to 0 to only display "plugin_projects_repositories" projects
-  # Projects listed in "plugin_projects_repositories" are not affected by this option
   plugin_projects_limit:
-    description: Maximum number of projects to display
+    description: |
+      Display limit
+
+      Note that `plugin_projects_repositories` is not affected by this option
     type: number
     default: 4
     min: 0
     max: 100
 
-  # List of repository projects to display, using the following format:
-  # :user/:repo/projects/:project_id
   plugin_projects_repositories:
-    description: List of repository project identifiers to disaplay
+    description: |
+      List of repositories projects
+
+      Use the following syntax for each project `:user/:repo/projects/:project_id`
     type: array
     example: username/repo/projects/1, username/repo/projects/2, ...
-    format:
-      - comma-separated
-      - /(?<user>[-a-z0-9]+)[/](?<repo>[-a-z0-9]+)[/]projects[/](?<id>[0-9]+)/
+    format: comma-separated
     default: ""
 
-  # Display projects descriptions
   plugin_projects_descriptions:
-    description: Display projects descriptions
+    description: Toggle projects descriptions display
     type: boolean
     default: no