doc(plugins/base): update

source/plugins/base/README.md

@@ -1,30 +1,31 @@
-### 🗃️ Base content
+<!--header-->
-
-The *base* content is all metrics enabled by default.
-
 <table>
+  <tr><th colspan="2"><h3>🗃️ Base content</h3></th></tr>
+  <tr><td colspan="2" align="center"></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> <a href="/source/templates/terminal"><code>📙 Terminal template</code></a></td>
+  </tr>
+  <tr>
+    <td><code>👤 Users</code> <code>👥 Organizations</code> <code>📓 Repositories</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"><table><tr>
 <td align="center">
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.classic.svg">
+<img src="https://github.com/lowlighter/metrics/blob/examples/metrics.classic.svg" alt=""></img>
-      <img width="900" height="1" alt="">
 </td>
 <td align="center">
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.organization.svg">
+<img src="https://github.com/lowlighter/metrics/blob/examples/metrics.organization.svg" alt=""></img>
-      <img width="900" height="1" alt="">
 </td>
+</tr></table></td>
   </tr>
 </table>
+<!--/header-->
 
-It contains the following sections:
+## ➡️ Available options
-* `header`, which usually contains your username, your two-week commits calendars and a few additional data
-* `activity`, which contains your recent activity (commits, pull requests, issues, etc.)
-* `community`, which contains your community stats (following, sponsors, organizations, etc.)
-* `repositories`, which contains your repositories stats (license, forks, stars, etc.)
-* `metadata`, which contains informations about generated metrics
-
-These are all enabled by default, but you can explicitely opt out from them.
-
-#### ➡️ Available options
 
 <!--options-->
 <table>
@@ -33,7 +34,16 @@ These are all enabled by default, but you can explicitely opt out from them.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>base</code></td>
-    <td rowspan="2"><p>Metrics base content</p>
+    <td rowspan="2"><p>Base content</p>
+<p>The following sections are supported:</p>
+<ul>
+<li><code>header</code>, which usually contains username, two-week commits calendars and a few additional data</li>
+<li><code>activity</code>, which contains recent activity (commits, pull requests, issues, etc.)</li>
+<li><code>community</code>, which contains community stats (following, sponsors, organizations, etc.)</li>
+<li><code>repositories</code>, which contains repositories stats (license, forks, stars, etc.)</li>
+<li><code>metadata</code>, which contains informations about generated metrics</li>
+</ul>
+<p>These are all enabled by default, but it is possible to explicitely opt out from them.</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -45,7 +55,8 @@ These are all enabled by default, but you can explicitely opt out from them.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>repositories</code></td>
-    <td rowspan="2"><p>Number of repositories to use</p>
+    <td rowspan="2"><p>Repositories to fetch</p>
+<p>A higher value result in more accurate metrics but can hit GitHub API rate-limit more easily (especially with a lot of plugins enabled)</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -57,7 +68,9 @@ These are all enabled by default, but you can explicitely opt out from them.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>repositories_batch</code></td>
-    <td rowspan="2"><p>Number of repositories to load at once by queries</p>
+    <td rowspan="2"><p>Repositories to fetch at a time</p>
+<p>If you receive <code>Something went wrong while executing your query</code> (which is usually caused by API timeout),
+try lowering this value.</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -70,7 +83,7 @@ These are all enabled by default, but you can explicitely opt out from them.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>repositories_forks</code></td>
-    <td rowspan="2"><p>Include forks in metrics</p>
+    <td rowspan="2"><p>Include forks</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -81,6 +94,14 @@ These are all enabled by default, but you can explicitely opt out from them.
   <tr>
     <td nowrap="nowrap"><code>repositories_affiliations</code></td>
     <td rowspan="2"><p>Repositories affiliations</p>
+<ul>
+<li><code>owner</code>: owned repositories</li>
+<li><code>collaborator</code>: repositories with push access</li>
+<li><code>organization_member</code>: repositories from an organization where user is a member</li>
+</ul>
+<p>Some plugin outputs may be affected by this setting too.</p>
+<p>Set to <code>&quot;&quot;</code> to disable and fetch all repositories related to you.
+Broad affiliation will result in less representative metrics.</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -92,7 +113,7 @@ These are all enabled by default, but you can explicitely opt out from them.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>repositories_skipped</code></td>
-    <td rowspan="2"><p>Default repositories to skip</p>
+    <td rowspan="2"><p>Default skipped repositories</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -103,7 +124,7 @@ These are all enabled by default, but you can explicitely opt out from them.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>users_ignored</code></td>
-    <td rowspan="2"><p>Default users to ignore</p>
+    <td rowspan="2"><p>Default ignored users</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -116,7 +137,8 @@ These are all enabled by default, but you can explicitely opt out from them.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>commits_authoring</code></td>
-    <td rowspan="2"><p>List of surnames or email addresses you use when authoring commits</p>
+    <td rowspan="2"><p>Name, username, email addresses that has been used for authoring commits</p>
+<p>This setting can be used to detect commits ownerships in some plugin</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -129,9 +151,7 @@ These are all enabled by default, but you can explicitely opt out from them.
 </table>
 <!--/options-->
 
-*[→ Full specification](metadata.yml)*
+## ℹ️ Examples workflows
-
-#### ℹ️ Examples workflows
 
 <!--examples-->
 ```yaml

source/plugins/base/metadata.yml

@@ -1,5 +1,9 @@
 name: "🗃️ Base content"
 category: core
+description:
+examples:
+  default1: https://github.com/lowlighter/metrics/blob/examples/metrics.classic.svg
+  default2: https://github.com/lowlighter/metrics/blob/examples/metrics.organization.svg
 supports:
   - user
   - organization
@@ -10,76 +14,91 @@ inputs:
 
   # Base content
   base:
-    description: Metrics base content
+    description: |
+      Base content
+
+      The following sections are supported:
+      * `header`, which usually contains username, two-week commits calendars and a few additional data
+      * `activity`, which contains recent activity (commits, pull requests, issues, etc.)
+      * `community`, which contains community stats (following, sponsors, organizations, etc.)
+      * `repositories`, which contains repositories stats (license, forks, stars, etc.)
+      * `metadata`, which contains informations about generated metrics
+
+      These are all enabled by default, but it is possible to explicitely opt out from them.
     type: array
     format: comma-separated
     default: header, activity, community, repositories, metadata
     values:
-      - header       # name, commits calendar, ...
+      - header
-      - activity     # commits, issues/pull requests opened, ...
+      - activity
-      - community    # following, stars, sponsors, ...
+      - community
-      - repositories # license, stars, forks, ...
+      - repositories
-      - metadata     # svg generation metadata
+      - metadata
 
-  # Number of repositories to use to computes metrics
-  # Using more will result in more accurate metrics, but you may hit GitHub rate-limit more easily if you use a lot of plugins
   repositories:
-    description: Number of repositories to use
+    description: |
+      Repositories to fetch
+
+      A higher value result in more accurate metrics but can hit GitHub API rate-limit more easily (especially with a lot of plugins enabled)
     type: number
     default: 100
     min: 0
 
-  # Number of repositories to load at once by queries
-  # If you encounter GitHub queries timeouts, using a lower value here may solve issues
   repositories_batch:
-    description: Number of repositories to load at once by queries
+    description: |
+      Repositories to fetch at a time
+
+      If you receive `Something went wrong while executing your query` (which is usually caused by API timeout),
+      try lowering this value.
     type: number
     default: 100
     max: 100
     min: 1
 
-  # Include forked repositories into metrics
   repositories_forks:
-    description: Include forks in metrics
+    description: Include forks
     type: boolean
     default: no
 
-  # Filter repositories by user affiliations (you can specify multiple affiliations constraints)
-  # Set to "" to use all repositories related to you
-  # Note that it may affect some plugin outputs (broad affiliations will result in less representative metrics)
   repositories_affiliations:
-    description: Repositories affiliations
+    description: |
+      Repositories affiliations
+      - `owner`: owned repositories
+      - `collaborator`: repositories with push access
+      - `organization_member`: repositories from an organization where user is a member
+
+      Some plugin outputs may be affected by this setting too.
+
+      Set to `""` to disable and fetch all repositories related to you.
+      Broad affiliation will result in less representative metrics.
     type: array
     format: comma-separated
     default: owner
     values:
-      - owner               # Use repositories you own
+      - owner
-      - collaborator        # Use repositories you push access
+      - collaborator
-      - organization_member # Use repositories where you're an organization member
+      - organization_member
 
-  # List of default repositories that will be skipped
-  # Plugins supporting a "skip repositories option" will automatically append repositories listed in this option
   repositories_skipped:
-    description: Default repositories to skip
+    description: Default skipped repositories
     type: array
     format: comma-separated
     default: ""
     example: my-repo-1, my-repo-2, owner/repo-3, ...
     global: yes
 
-  # List of default ignored users
-  # Plugins supporting a "skip users option" will automatically append users listed in this option
   users_ignored:
-    description: Default users to ignore
+    description: Default ignored users
     type: array
     format: comma-separated
     default: github-actions[bot], dependabot[bot], dependabot-preview[bot]
     global: yes
 
-  # List of surnames or email addresses you use when authoring commits
-  # These are mostly used to perform commits analysis to detect ownership
   commits_authoring:
-    description: List of surnames or email addresses you use when authoring commits
+    description: |
+      Name, username, email addresses that has been used for authoring commits
+
+      This setting can be used to detect commits ownerships in some plugin
     type: array
     format: comma-seperated
     default: .user.login