docs: updated workflows examples and options descriptions (#772) [skip ci]

Author: lowlighter

.github/examples.mjs

@@ -0,0 +1,44 @@
+//Imports
+import fs from "fs/promises"
+import fss from "fs"
+import paths from "path"
+import url from "url"
+import metadata from "../source/app/metrics/metadata.mjs"
+import yaml from "js-yaml"
+
+//Paths
+const __metrics = paths.join(paths.dirname(url.fileURLToPath(import.meta.url)), "..")
+const __templates = paths.join(paths.join(__metrics, "source/templates/"))
+const __plugins = paths.join(paths.join(__metrics, "source/plugins/"))
+
+//Load plugins metadata
+const {plugins, templates} = await metadata({log:false, diff:true})
+
+async function plugin(id) {
+  const path = paths.join(__plugins, id)
+  const readme = paths.join(path, "README.md")
+  const examples = paths.join(path, "examples.yml")
+  return {
+    readme:{
+      path:readme,
+      content:`${await fs.readFile(readme)}`
+    },
+    examples:fss.existsSync(examples) ? yaml.load(await fs.readFile(examples), "utf8") ?? [] : [],
+    options:plugins[id].readme.table
+  }
+}
+
+//Plugins
+for (const id of Object.keys(plugins)) {
+  const {examples, options, readme} = await plugin(id)
+  //Plugin readme
+  await fs.writeFile(readme.path, readme.content
+    .replace(/(<!--examples-->)[\s\S]*(<!--\/examples-->)/g, `$1\n${examples.map(({test, prod, ...step}) => ["```yaml", yaml.dump(step), "```"].join("\n")).join("\n")}\n$2`)
+    .replace(/(<!--options-->)[\s\S]*(<!--\/options-->)/g, `$1\n${options}\n$2`)
+  )
+  //Plugin tests
+}
+
+//Templates
+
+//Workflow

source/app/metrics/metadata.mjs

@@ -3,12 +3,16 @@ import fs from "fs"
 import yaml from "js-yaml"
 import path from "path"
 import url from "url"
+import fetch from "node-fetch"
 
 //Defined categories
 const categories = ["core", "github", "social", "community"]
 
+//Previous descriptors
+let previous = null
+
 /**Metadata descriptor parser */
-export default async function metadata({log = true} = {}) {
+export default async function metadata({log = true, diff = false} = {}) {
   //Paths
   const __metrics = path.join(path.dirname(url.fileURLToPath(import.meta.url)), "../../..")
   const __templates = path.join(__metrics, "source/templates")
@@ -19,6 +23,16 @@ export default async function metadata({log = true} = {}) {
   //Init
   const logger = log ? console.debug : () => null
 
+  //Diff with latest version
+  if (diff) {
+    try {
+      previous = yaml.load(await fetch("https://raw.githubusercontent.com/lowlighter/metrics/latest/action.yml").then(response => response.text()))
+    }
+    catch (error) {
+      logger(error)
+    }
+  }
+
   //Load plugins metadata
   let Plugins = {}
   logger("metrics/metadata > loading plugins metadata")
@@ -254,8 +268,47 @@ metadata.plugin = async function({__plugins, name, logger}) {
       const raw = `${await fs.promises.readFile(path.join(__plugins, name, "README.md"), "utf-8")}`
       const demo = raw.match(/(?<demo><table>[\s\S]*?<[/]table>)/)?.groups?.demo?.replace(/<[/]?(?:table|tr)>/g, "")?.trim() ?? "<td></td>"
 
+      //Options table
+      const table = [
+        "| Option | Type *(format)* **[default]** *{allowed values}* | Description |",
+        "| ------ | -------------------------------- | ----------- |",
+        Object.entries(inputs).map(([option, {description, type, ...o}]) => {
+          let row = []
+          {
+            const cell = [`${"`"}${option}${"`"}`]
+            if (type === "token")
+              cell.push("🔐")
+            if (!Object.keys(previous?.inputs ?? {}).includes(option))
+              cell.push("✨")
+            row.push(cell.join(" "))
+          }
+          {
+            const cell = [`${"`"}${type}${"`"}`]
+            if ("format" in o)
+              cell.push(`*(${o.format})*`)
+            if ("default" in o)
+              cell.push(`**[${o.default}]**`)
+            if ("values" in o)
+              cell.push(`*{${o.values.map(value => `"${value}"`).join(", ")}}*`)
+            if ("min" in o)
+              cell.push(`*{${o.min} ≤`)
+            if (("min" in o)||("max" in o))
+              cell.push(`${"min" in o ? "" : "*{"}𝑥${"max" in o ? "" : "}*"}`)
+            if ("max" in o)
+              cell.push(`≤ ${o.max}}*`)
+            row.push(cell.join(" "))
+          }
+          row.push(description)
+          return `| ${row.join(" | ")} |`
+        }).join("\n"),
+        "\n",
+        "Legend for option icons:",
+        "* 🔐 Value should be stored in repository secrets",
+        "* ✨ New feature currently in testing on `master`/`main`"
+      ].flat(Infinity).filter(s => s).join("\n")
+
       //Readme descriptor
-      meta.readme = {demo}
+      meta.readme = {demo, table}
     }
 
     //Icon

source/plugins/achievements/README.md

@@ -27,19 +27,54 @@ It also lets you quickly see at a glance what this user primarly use GitHub for,
 
 ![Ranks](/.github/readme/imgs/plugin_achievements_ranks.png)
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_achievements` | `boolean` **[no]** | Display achievements |
+| `plugin_achievements_threshold` | `string` **[C]** *{"S", "A", "B", "C", "X"}* | Display rank minimal threshold |
+| `plugin_achievements_secrets` | `boolean` **[yes]** | Display unlocked secrets achievements |
+| `plugin_achievements_display` | `string` **[detailed]** *{"detailed", "compact"}* | Achievements display style |
+| `plugin_achievements_limit` | `number` **[0]** *{0 ≤ 𝑥}* | Maximum number of achievements to display |
+| `plugin_achievements_ignored` | `array` *(comma-separated)* **[]** | Unlocked achievements to hide |
+| `plugin_achievements_only` | `array` *(comma-separated)* **[]** | Unlocked achievements to display |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
+```yaml
+name: Detailed display
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.achievements.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_achievements: 'yes'
+  plugin_achievements_only: sponsor, maintainer, octonaut
 
+```
 ```yaml
-- uses: lowlighter/metrics@latest
-  with:
-    # ... other options
-    plugin_achievements: yes
-    plugin_achievements_threshold: B      # Display achievements with rank B or higher
-    plugin_achievements_secrets: yes      # Display unlocked secrets achievements
-    plugin_achievements_display: compact  # Use compact display
-    plugin_achievements_limit: 0          # Display all unlocked achievements (no limit)
-    plugin_achievements_ignored: octonaut # Hide "octonaut" achievement
-    plugin_achievements_only: explorer    # Display only "explorer" achievement (don't use with "ignored" option)
+name: Compact display
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.achievements.compact.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_achievements: 'yes'
+  plugin_achievements_only: >-
+    polyglot, stargazer, sponsor, deployer, member, maintainer, developer,
+    scripter, packager, explorer, infographile, manager
+  plugin_achievements_display: compact
+  plugin_achievements_threshold: X
+
 ```
+<!--/examples-->

source/plugins/achievements/examples.yml

@@ -0,0 +1,23 @@
+- name: Detailed display
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.achievements.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_achievements: yes
+    plugin_achievements_only: sponsor, maintainer, octonaut
+  test:
+    timeout: 900000
+
+- name: Compact display
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.achievements.compact.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_achievements: yes
+    plugin_achievements_only: polyglot, stargazer, sponsor, deployer, member, maintainer, developer, scripter, packager, explorer, infographile, manager
+    plugin_achievements_display: compact
+    plugin_achievements_threshold: X
+  test:
+    timeout: 900000

source/plugins/activity/README.md

@@ -29,20 +29,43 @@ It uses data from [GitHub events](https://docs.github.com/en/free-pro-team@lates
 
 Use a full `repo` scope token to display **private** events.
 
-#### ℹ️ Examples workflows
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_activity` | `boolean` **[no]** | Display recent activity |
+| `plugin_activity_limit` | `number` **[5]** *{1 ≤ 𝑥 ≤ 1000}* | Maximum number of events to display |
+| `plugin_activity_load` | `number` **[300]** *{100 ≤ 𝑥 ≤ 1000}* | Number of events to load |
+| `plugin_activity_days` | `number` **[14]** *{0 ≤ 𝑥 ≤ 365}* | Maximum event age |
+| `plugin_activity_filter` | `array` *(comma-separated)* **[all]** *{"all", "comment", "ref/create", "ref/delete", "release", "push", "issue", "pr", "review", "wiki", "fork", "star", "member", "public"}* | Events types to keep |
+| `plugin_activity_visibility` | `string` **[all]** *{"public", "all"}* | Set events visibility |
+| `plugin_activity_timestamps` | `boolean` **[no]** | Display events timestamps |
+| `plugin_activity_skipped` | `array` *(comma-separated)* **[]** | Repositories to skip |
+| `plugin_activity_ignored` | `undefined` **[github-actions[bot], dependabot[bot], dependabot-preview[bot]]** | Actors to ignore |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
 
-[➡️ Available options for this plugin](metadata.yml)
+*[→ Full specification](metadata.yml)*
 
+#### ℹ️ Examples workflows
+
+<!--examples-->
 ```yaml
-- uses: lowlighter/metrics@latest
-  with:
-    # ... other options
-    plugin_activity: yes
-    plugin_activity_limit: 5           # Limit to 5 events
-    plugin_activity_load: 100          # Load up to 100 recent events from API (should be higher than "limit")
-    plugin_activity_days: 14           # Keep only events from last 14 days (set to 0 for no limit)
-    plugin_activity_filter: all        # Show all events (use table above to filter events types)
-    plugin_activity_visibility: public # Only display public events
-    plugin_activity_timestamps: yes    # Display events timestamps
-    plugin_activity_skipped: repo      # Ignored repositories
+name: Recent activity
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.activity.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_activity: 'yes'
+  plugin_activity_limit: 5
+  plugin_activity_days: 0
+  plugin_activity_filter: issue, pr, release, fork, review, ref/create
+
 ```
+<!--/examples-->

source/plugins/activity/examples.yml

@@ -0,0 +1,10 @@
+- name: Recent activity
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.activity.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_activity: yes
+    plugin_activity_limit: 5
+    plugin_activity_days: 0
+    plugin_activity_filter: issue, pr, release, fork, review, ref/create

source/plugins/anilist/README.md

@@ -25,19 +25,63 @@ This plugin is composed of the following sections, which can be displayed or hid
 
 These sections can also be filtered by media type, which can be either `anime`, `manga` or both.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_anilist` | `boolean` **[no]** | Display data from your AniList account |
+| `plugin_anilist_medias` | `array` *(comma-separated)* **[anime, manga]** *{"anime", "manga"}* | Medias types to display |
+| `plugin_anilist_sections` | `array` *(comma-separated)* **[favorites]** *{"favorites", "watching", "reading", "characters"}* | Sections to display |
+| `plugin_anilist_limit` | `number` **[2]** *{0 ≤ 𝑥}* | Maximum number of entries to display per section |
+| `plugin_anilist_limit_characters` | `number` **[22]** *{0 ≤ 𝑥}* | Maximum number of entries to display in characters section |
+| `plugin_anilist_shuffle` | `boolean` **[yes]** | Shuffle AniList data |
+| `plugin_anilist_user` | `string` **[.user.login]** | AniList login |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
+```yaml
+name: Favorites anime and currently watching
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.anilist.svg
+  token: NOT_NEEDED
+  plugin_anilist: 'yes'
+  plugin_anilist_medias: anime
+  plugin_anilist_sections: favorites, watching
+  plugin_anilist_limit: 1
 
+```
 ```yaml
-- uses: lowlighter/metrics@latest
-  with:
-    # ... other options
-    plugin_anilist: yes
-    plugin_anilist_medias: anime, manga            # Display both animes and mangas
-    plugin_anilist_sections: favorites, characters # Display only favorites and characters sections
-    plugin_anilist_limit: 2                        # Limit to 2 entry per section (characters section excluded)
-    plugin_anilist_limit_characters: 22            # Limit to 22 characters in characters section
-    plugin_anilist_shuffle: yes                    # Shuffle data for more varied outputs
-    plugin_anilist_user: .user.login               # Use same username as GitHub login
+name: Favorites manga and currently reading
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.anilist.manga.svg
+  token: NOT_NEEDED
+  plugin_anilist: 'yes'
+  plugin_anilist_medias: manga
+  plugin_anilist_sections: favorites, reading
+  plugin_anilist_limit: 1
+
+```
+```yaml
+name: Favorites characters
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.anilist.characters.svg
+  token: NOT_NEEDED
+  plugin_anilist: 'yes'
+  plugin_anilist_sections: characters
+  plugin_anilist_limit_characters: 22
+
 ```
+<!--/examples-->

source/plugins/anilist/examples.yml

@@ -0,0 +1,28 @@
+- name: Favorites anime and currently watching
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.anilist.svg
+    token: NOT_NEEDED
+    plugin_anilist: yes
+    plugin_anilist_medias: anime
+    plugin_anilist_sections: favorites, watching
+    plugin_anilist_limit: 1
+
+- name: Favorites manga and currently reading
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.anilist.manga.svg
+    token: NOT_NEEDED
+    plugin_anilist: yes
+    plugin_anilist_medias: manga
+    plugin_anilist_sections: favorites, reading
+    plugin_anilist_limit: 1
+
+- name: Favorites characters
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.anilist.characters.svg
+    token: NOT_NEEDED
+    plugin_anilist: yes
+    plugin_anilist_sections: characters
+    plugin_anilist_limit_characters: 22