doc(plugins/base): update

2022-01-15 19:25:28 -05:00
parent 1007e25d35
commit da57541e38
2 changed files with 101 additions and 62 deletions
--- a/source/plugins/base/README.md
+++ b/source/plugins/base/README.md
@@ -1,30 +1,31 @@
-### 🗃️ Base content
-
-The *base* content is all metrics enabled by default.
-
+<!--header-->
 <table>
+  <tr><th colspan="2"><h3>🗃️ Base content</h3></th></tr>
+  <tr><td colspan="2" align="center"></td></tr>
  <tr>
-    <td align="center">
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.classic.svg">
-      <img width="900" height="1" alt="">
-    </td>
-    <td align="center">
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.organization.svg">
-      <img width="900" height="1" alt="">
-    </td>
+    <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" alt=""></img>
+</td>
+<td align="center">
+<img src="https://github.com/lowlighter/metrics/blob/examples/metrics.organization.svg" alt=""></img>
+</td>
+</tr></table></td>
  </tr>
 </table>
+<!--/header-->

-It contains the following sections:
-* `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
+## ➡️ 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
--- a/source/plugins/base/metadata.yml
+++ b/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, ...
-      - activity     # commits, issues/pull requests opened, ...
-      - community    # following, stars, sponsors, ...
-      - repositories # license, stars, forks, ...
-      - metadata     # svg generation metadata
+      - header
+      - activity
+      - community
+      - repositories
+      - 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
-      - collaborator        # Use repositories you push access
-      - organization_member # Use repositories where you're an organization member
+      - owner
+      - collaborator
+      - 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