Skip to content

Commit 4d06539

Browse files
lowlighterlowlighter
authored
docs: updated workflows examples and options descriptions (lowlighter#772) [skip ci]
1 parent 44e3992 commit 4d06539

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

80 files changed

+2271
-429
lines changed

‎.github/examples.mjs‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
//Imports
2+
import fs from "fs/promises"
3+
import fss from "fs"
4+
import paths from "path"
5+
import url from "url"
6+
import metadata from "../source/app/metrics/metadata.mjs"
7+
import yaml from "js-yaml"
8+
9+
//Paths
10+
const __metrics = paths.join(paths.dirname(url.fileURLToPath(import.meta.url)), "..")
11+
const __templates = paths.join(paths.join(__metrics, "source/templates/"))
12+
const __plugins = paths.join(paths.join(__metrics, "source/plugins/"))
13+
14+
//Load plugins metadata
15+
const {plugins, templates} = await metadata({log:false, diff:true})
16+
17+
async function plugin(id) {
18+
const path = paths.join(__plugins, id)
19+
const readme = paths.join(path, "README.md")
20+
const examples = paths.join(path, "examples.yml")
21+
return {
22+
readme:{
23+
path:readme,
24+
content:`${await fs.readFile(readme)}`
25+
},
26+
examples:fss.existsSync(examples) ? yaml.load(await fs.readFile(examples), "utf8") ?? [] : [],
27+
options:plugins[id].readme.table
28+
}
29+
}
30+
31+
//Plugins
32+
for (const id of Object.keys(plugins)) {
33+
const {examples, options, readme} = await plugin(id)
34+
//Plugin readme
35+
await fs.writeFile(readme.path, readme.content
36+
.replace(/(<!--examples-->)[\s\S]*(<!--\/examples-->)/g, `$1\n${examples.map(({test, prod, ...step}) => ["```yaml", yaml.dump(step), "```"].join("\n")).join("\n")}\n$2`)
37+
.replace(/(<!--options-->)[\s\S]*(<!--\/options-->)/g, `$1\n${options}\n$2`)
38+
)
39+
//Plugin tests
40+
}
41+
42+
//Templates
43+
44+
//Workflow

‎source/app/metrics/metadata.mjs‎

Lines changed: 55 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,16 @@ import fs from "fs"
33
import yaml from "js-yaml"
44
import path from "path"
55
import url from "url"
6+
import fetch from "node-fetch"
67

78
//Defined categories
89
const categories = ["core", "github", "social", "community"]
910

11+
//Previous descriptors
12+
let previous = null
13+
1014
/**Metadata descriptor parser */
11-
export default async function metadata({log = true} = {}) {
15+
export default async function metadata({log = true, diff = false} = {}) {
1216
//Paths
1317
const __metrics = path.join(path.dirname(url.fileURLToPath(import.meta.url)), "../../..")
1418
const __templates = path.join(__metrics, "source/templates")
@@ -19,6 +23,16 @@ export default async function metadata({log = true} = {}) {
1923
//Init
2024
const logger = log ? console.debug : () => null
2125

26+
//Diff with latest version
27+
if (diff) {
28+
try {
29+
previous = yaml.load(await fetch("https://raw.githubusercontent.com/lowlighter/metrics/latest/action.yml").then(response => response.text()))
30+
}
31+
catch (error) {
32+
logger(error)
33+
}
34+
}
35+
2236
//Load plugins metadata
2337
let Plugins = {}
2438
logger("metrics/metadata > loading plugins metadata")
@@ -254,8 +268,47 @@ metadata.plugin = async function({__plugins, name, logger}) {
254268
const raw = `${await fs.promises.readFile(path.join(__plugins, name, "README.md"), "utf-8")}`
255269
const demo = raw.match(/(?<demo><table>[\s\S]*?<[/]table>)/)?.groups?.demo?.replace(/<[/]?(?:table|tr)>/g, "")?.trim() ?? "<td></td>"
256270

271+
//Options table
272+
const table = [
273+
"| Option | Type *(format)* **[default]** *{allowed values}* | Description |",
274+
"| ------ | -------------------------------- | ----------- |",
275+
Object.entries(inputs).map(([option, {description, type, ...o}]) => {
276+
let row = []
277+
{
278+
const cell = [`${"`"}${option}${"`"}`]
279+
if (type === "token")
280+
cell.push("🔐")
281+
if (!Object.keys(previous?.inputs ?? {}).includes(option))
282+
cell.push("✨")
283+
row.push(cell.join(" "))
284+
}
285+
{
286+
const cell = [`${"`"}${type}${"`"}`]
287+
if ("format" in o)
288+
cell.push(`*(${o.format})*`)
289+
if ("default" in o)
290+
cell.push(`**[${o.default}]**`)
291+
if ("values" in o)
292+
cell.push(`*{${o.values.map(value => `"${value}"`).join(", ")}}*`)
293+
if ("min" in o)
294+
cell.push(`*{${o.min} ≤`)
295+
if (("min" in o)||("max" in o))
296+
cell.push(`${"min" in o ? "" : "*{"}𝑥${"max" in o ? "" : "}*"}`)
297+
if ("max" in o)
298+
cell.push(`≤ ${o.max}}*`)
299+
row.push(cell.join(" "))
300+
}
301+
row.push(description)
302+
return `| ${row.join(" | ")} |`
303+
}).join("\n"),
304+
"\n",
305+
"Legend for option icons:",
306+
"* 🔐 Value should be stored in repository secrets",
307+
"* ✨ New feature currently in testing on `master`/`main`"
308+
].flat(Infinity).filter(s => s).join("\n")
309+
257310
//Readme descriptor
258-
meta.readme = {demo}
311+
meta.readme = {demo, table}
259312
}
260313

261314
//Icon

‎source/plugins/achievements/README.md‎

Lines changed: 46 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -27,19 +27,54 @@ It also lets you quickly see at a glance what this user primarly use GitHub for,
2727

2828
![Ranks](/.github/readme/imgs/plugin_achievements_ranks.png)
2929

30+
#### ➡️ Available options
31+
32+
<!--options-->
33+
| Option | Type *(format)* **[default]** *{allowed values}* | Description |
34+
| ------ | -------------------------------- | ----------- |
35+
| `plugin_achievements` | `boolean` **[no]** | Display achievements |
36+
| `plugin_achievements_threshold` | `string` **[C]** *{"S", "A", "B", "C", "X"}* | Display rank minimal threshold |
37+
| `plugin_achievements_secrets` | `boolean` **[yes]** | Display unlocked secrets achievements |
38+
| `plugin_achievements_display` | `string` **[detailed]** *{"detailed", "compact"}* | Achievements display style |
39+
| `plugin_achievements_limit` | `number` **[0]** *{0 ≤ 𝑥}* | Maximum number of achievements to display |
40+
| `plugin_achievements_ignored` | `array` *(comma-separated)* **[]** | Unlocked achievements to hide |
41+
| `plugin_achievements_only` | `array` *(comma-separated)* **[]** | Unlocked achievements to display |
42+
43+
44+
Legend for option icons:
45+
* 🔐 Value should be stored in repository secrets
46+
* ✨ New feature currently in testing on `master`/`main`
47+
<!--/options-->
48+
49+
*[→ Full specification](metadata.yml)*
50+
3051
#### ℹ️ Examples workflows
3152

32-
[➡️ Available options for this plugin](metadata.yml)
53+
<!--examples-->
54+
```yaml
55+
name: Detailed display
56+
uses: lowlighter/metrics@latest
57+
with:
58+
filename: metrics.plugin.achievements.svg
59+
token: ${{ secrets.METRICS_TOKEN }}
60+
base: ''
61+
plugin_achievements: 'yes'
62+
plugin_achievements_only: sponsor, maintainer, octonaut
3363

64+
```
3465
```yaml
35-
- uses: lowlighter/metrics@latest
36-
with:
37-
# ... other options
38-
plugin_achievements: yes
39-
plugin_achievements_threshold: B # Display achievements with rank B or higher
40-
plugin_achievements_secrets: yes # Display unlocked secrets achievements
41-
plugin_achievements_display: compact # Use compact display
42-
plugin_achievements_limit: 0 # Display all unlocked achievements (no limit)
43-
plugin_achievements_ignored: octonaut # Hide "octonaut" achievement
44-
plugin_achievements_only: explorer # Display only "explorer" achievement (don't use with "ignored" option)
66+
name: Compact display
67+
uses: lowlighter/metrics@latest
68+
with:
69+
filename: metrics.plugin.achievements.compact.svg
70+
token: ${{ secrets.METRICS_TOKEN }}
71+
base: ''
72+
plugin_achievements: 'yes'
73+
plugin_achievements_only: >-
74+
polyglot, stargazer, sponsor, deployer, member, maintainer, developer,
75+
scripter, packager, explorer, infographile, manager
76+
plugin_achievements_display: compact
77+
plugin_achievements_threshold: X
78+
4579
```
80+
<!--/examples-->

‎source/plugins/achievements/examples.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
- name: Detailed display
2+
uses: lowlighter/metrics@latest
3+
with:
4+
filename: metrics.plugin.achievements.svg
5+
token: ${{ secrets.METRICS_TOKEN }}
6+
base: ""
7+
plugin_achievements: yes
8+
plugin_achievements_only: sponsor, maintainer, octonaut
9+
test:
10+
timeout: 900000
11+
12+
- name: Compact display
13+
uses: lowlighter/metrics@latest
14+
with:
15+
filename: metrics.plugin.achievements.compact.svg
16+
token: ${{ secrets.METRICS_TOKEN }}
17+
base: ""
18+
plugin_achievements: yes
19+
plugin_achievements_only: polyglot, stargazer, sponsor, deployer, member, maintainer, developer, scripter, packager, explorer, infographile, manager
20+
plugin_achievements_display: compact
21+
plugin_achievements_threshold: X
22+
test:
23+
timeout: 900000

‎source/plugins/activity/README.md‎

Lines changed: 36 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -29,20 +29,43 @@ It uses data from [GitHub events](https://docs.github.com/en/free-pro-team@lates
2929

3030
Use a full `repo` scope token to display **private** events.
3131

32-
#### ℹ️ Examples workflows
32+
#### ➡️ Available options
33+
34+
<!--options-->
35+
| Option | Type *(format)* **[default]** *{allowed values}* | Description |
36+
| ------ | -------------------------------- | ----------- |
37+
| `plugin_activity` | `boolean` **[no]** | Display recent activity |
38+
| `plugin_activity_limit` | `number` **[5]** *{1 ≤ 𝑥 ≤ 1000}* | Maximum number of events to display |
39+
| `plugin_activity_load` | `number` **[300]** *{100 ≤ 𝑥 ≤ 1000}* | Number of events to load |
40+
| `plugin_activity_days` | `number` **[14]** *{0 ≤ 𝑥 ≤ 365}* | Maximum event age |
41+
| `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 |
42+
| `plugin_activity_visibility` | `string` **[all]** *{"public", "all"}* | Set events visibility |
43+
| `plugin_activity_timestamps` | `boolean` **[no]** | Display events timestamps |
44+
| `plugin_activity_skipped` | `array` *(comma-separated)* **[]** | Repositories to skip |
45+
| `plugin_activity_ignored` | `undefined` **[github-actions[bot], dependabot[bot], dependabot-preview[bot]]** | Actors to ignore |
46+
47+
48+
Legend for option icons:
49+
* 🔐 Value should be stored in repository secrets
50+
* ✨ New feature currently in testing on `master`/`main`
51+
<!--/options-->
3352

34-
[➡️ Available options for this plugin](metadata.yml)
53+
*[→ Full specification](metadata.yml)*
3554

55+
#### ℹ️ Examples workflows
56+
57+
<!--examples-->
3658
```yaml
37-
- uses: lowlighter/metrics@latest
38-
with:
39-
# ... other options
40-
plugin_activity: yes
41-
plugin_activity_limit: 5 # Limit to 5 events
42-
plugin_activity_load: 100 # Load up to 100 recent events from API (should be higher than "limit")
43-
plugin_activity_days: 14 # Keep only events from last 14 days (set to 0 for no limit)
44-
plugin_activity_filter: all # Show all events (use table above to filter events types)
45-
plugin_activity_visibility: public # Only display public events
46-
plugin_activity_timestamps: yes # Display events timestamps
47-
plugin_activity_skipped: repo # Ignored repositories
59+
name: Recent activity
60+
uses: lowlighter/metrics@latest
61+
with:
62+
filename: metrics.plugin.activity.svg
63+
token: ${{ secrets.METRICS_TOKEN }}
64+
base: ''
65+
plugin_activity: 'yes'
66+
plugin_activity_limit: 5
67+
plugin_activity_days: 0
68+
plugin_activity_filter: issue, pr, release, fork, review, ref/create
69+
4870
```
71+
<!--/examples-->

‎source/plugins/activity/examples.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
- name: Recent activity
2+
uses: lowlighter/metrics@latest
3+
with:
4+
filename: metrics.plugin.activity.svg
5+
token: ${{ secrets.METRICS_TOKEN }}
6+
base: ""
7+
plugin_activity: yes
8+
plugin_activity_limit: 5
9+
plugin_activity_days: 0
10+
plugin_activity_filter: issue, pr, release, fork, review, ref/create

‎source/plugins/anilist/README.md‎

Lines changed: 55 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -25,19 +25,63 @@ This plugin is composed of the following sections, which can be displayed or hid
2525

2626
These sections can also be filtered by media type, which can be either `anime`, `manga` or both.
2727

28+
#### ➡️ Available options
29+
30+
<!--options-->
31+
| Option | Type *(format)* **[default]** *{allowed values}* | Description |
32+
| ------ | -------------------------------- | ----------- |
33+
| `plugin_anilist` | `boolean` **[no]** | Display data from your AniList account |
34+
| `plugin_anilist_medias` | `array` *(comma-separated)* **[anime, manga]** *{"anime", "manga"}* | Medias types to display |
35+
| `plugin_anilist_sections` | `array` *(comma-separated)* **[favorites]** *{"favorites", "watching", "reading", "characters"}* | Sections to display |
36+
| `plugin_anilist_limit` | `number` **[2]** *{0 ≤ 𝑥}* | Maximum number of entries to display per section |
37+
| `plugin_anilist_limit_characters` | `number` **[22]** *{0 ≤ 𝑥}* | Maximum number of entries to display in characters section |
38+
| `plugin_anilist_shuffle` | `boolean` **[yes]** | Shuffle AniList data |
39+
| `plugin_anilist_user` | `string` **[.user.login]** | AniList login |
40+
41+
42+
Legend for option icons:
43+
* 🔐 Value should be stored in repository secrets
44+
* ✨ New feature currently in testing on `master`/`main`
45+
<!--/options-->
46+
47+
*[→ Full specification](metadata.yml)*
48+
2849
#### ℹ️ Examples workflows
2950

30-
[➡️ Available options for this plugin](metadata.yml)
51+
<!--examples-->
52+
```yaml
53+
name: Favorites anime and currently watching
54+
uses: lowlighter/metrics@latest
55+
with:
56+
filename: metrics.plugin.anilist.svg
57+
token: NOT_NEEDED
58+
plugin_anilist: 'yes'
59+
plugin_anilist_medias: anime
60+
plugin_anilist_sections: favorites, watching
61+
plugin_anilist_limit: 1
3162

63+
```
3264
```yaml
33-
- uses: lowlighter/metrics@latest
34-
with:
35-
# ... other options
36-
plugin_anilist: yes
37-
plugin_anilist_medias: anime, manga # Display both animes and mangas
38-
plugin_anilist_sections: favorites, characters # Display only favorites and characters sections
39-
plugin_anilist_limit: 2 # Limit to 2 entry per section (characters section excluded)
40-
plugin_anilist_limit_characters: 22 # Limit to 22 characters in characters section
41-
plugin_anilist_shuffle: yes # Shuffle data for more varied outputs
42-
plugin_anilist_user: .user.login # Use same username as GitHub login
65+
name: Favorites manga and currently reading
66+
uses: lowlighter/metrics@latest
67+
with:
68+
filename: metrics.plugin.anilist.manga.svg
69+
token: NOT_NEEDED
70+
plugin_anilist: 'yes'
71+
plugin_anilist_medias: manga
72+
plugin_anilist_sections: favorites, reading
73+
plugin_anilist_limit: 1
74+
75+
```
76+
```yaml
77+
name: Favorites characters
78+
uses: lowlighter/metrics@latest
79+
with:
80+
filename: metrics.plugin.anilist.characters.svg
81+
token: NOT_NEEDED
82+
plugin_anilist: 'yes'
83+
plugin_anilist_sections: characters
84+
plugin_anilist_limit_characters: 22
85+
4386
```
87+
<!--/examples-->

‎source/plugins/anilist/examples.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
- name: Favorites anime and currently watching
2+
uses: lowlighter/metrics@latest
3+
with:
4+
filename: metrics.plugin.anilist.svg
5+
token: NOT_NEEDED
6+
plugin_anilist: yes
7+
plugin_anilist_medias: anime
8+
plugin_anilist_sections: favorites, watching
9+
plugin_anilist_limit: 1
10+
11+
- name: Favorites manga and currently reading
12+
uses: lowlighter/metrics@latest
13+
with:
14+
filename: metrics.plugin.anilist.manga.svg
15+
token: NOT_NEEDED
16+
plugin_anilist: yes
17+
plugin_anilist_medias: manga
18+
plugin_anilist_sections: favorites, reading
19+
plugin_anilist_limit: 1
20+
21+
- name: Favorites characters
22+
uses: lowlighter/metrics@latest
23+
with:
24+
filename: metrics.plugin.anilist.characters.svg
25+
token: NOT_NEEDED
26+
plugin_anilist: yes
27+
plugin_anilist_sections: characters
28+
plugin_anilist_limit_characters: 22

0 commit comments

Comments
 (0)