Skip to content

Commit

Permalink
docs: updated workflows examples and options descriptions (lowlighter…
Browse files Browse the repository at this point in the history
…#772) [skip ci]
  • Loading branch information
lowlighter authored Jan 14, 2022
1 parent 44e3992 commit 4d06539
Show file tree
Hide file tree
Showing 80 changed files with 2,271 additions and 429 deletions.
44 changes: 44 additions & 0 deletions .github/examples.mjs
Original file line number Diff line number Diff line change
@@ -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
57 changes: 55 additions & 2 deletions source/app/metrics/metadata.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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")
Expand Down Expand Up @@ -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
Expand Down
57 changes: 46 additions & 11 deletions source/plugins/achievements/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-->
23 changes: 23 additions & 0 deletions source/plugins/achievements/examples.yml
Original file line number Diff line number Diff line change
@@ -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
49 changes: 36 additions & 13 deletions source/plugins/activity/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-->
10 changes: 10 additions & 0 deletions source/plugins/activity/examples.yml
Original file line number Diff line number Diff line change
@@ -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
66 changes: 55 additions & 11 deletions source/plugins/anilist/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-->
28 changes: 28 additions & 0 deletions source/plugins/anilist/examples.yml
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit 4d06539

Please sign in to comment.