sudacode/metrics
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(plugins/languages): full rewrite

Browse Source
This commit is contained in:
lowlighter
2022-01-15 12:06:05 -05:00
parent 8f1e017beb
commit 72c736c5b7
2 changed files with 175 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
source/plugins/languages/README.md
View File

@@ -1,139 +1,139 @@
### 🈷️ Most used languages <!--header-->
<!--/header-->
The *languages* plugin displays which programming languages you use the most across all your repositories. ## ➡️ Available options
<table>
<td align="center">
<details open><summary>Indepth analysis (clone and analyze repositories)</summary>
<img src="https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.languages.indepth.svg">
</details>
<details open><summary>Recently used (analyze recent activity events)</summary>
<img src="https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.languages.recent.svg">
</details>
<details><summary>Default algorithm</summary>
<img src="https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.languages.svg">
</details>
<details><summary>Default algorithm (with details)</summary>
<img src="https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.languages.details.svg">
</details>
<img width="900" height="1" alt="">
</td>
</table>
It is possible to use custom colors for languages instead of those provided by GitHub by using `plugin_languages_colors` option.
You can specify either an index with a color, or a language name (case insensitive) with a color.
Colors can be either in hexadecimal format or a [named color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
It is also possible to use a predefined set of colors from [colorsets.json](colorsets.json)
#### Using `indepth` statistics
Languages statistics are computed using the top languages provided by GitHub of each repository you contributed to.
If you work a lot with other people, these numbers may be less representative of your actual work.
The `plugin_languages_indepth` option lets you get more accurate metrics by cloning each repository you contributed to, running [linguist-js](https://github.com/Nixinova/Linguist) and then iterating over patches matching your username from `git log`. This method is slower than the first one.
> ⚠️ Although *metrics* does not send any code to external sources, you must understand that when using this option repositories are cloned locally temporarly on the GitHub Action runner. If you work with sensitive data or company code, it is advised to keep this option disabled. *Metrics* and its authors cannot be held responsible for any resulting code leaks, use at your own risk.
> Source code is available for auditing at [analyzers.mjs](/source/plugins/languages/analyzers.mjs)
> 🔣 On web instances, `indepth` is an extra feature and must be enabled globally in `settings.json`
#### `commits_authoring` option
Since Git lets you use any email and name for commits, metrics may not be able to detect whether you own a commit or not. By default, it'll check whether it matches your GitHub login.
For better results, it's advised to add either your surnames and eventually no-reply email addresses.
#### ➡️ Available options
<!--options--> <!--options-->
| Option | Type *(format)* **[default]** *{allowed values}* | Description |
| ------ | -------------------------------- | ----------- |
| `plugin_languages` | `boolean` **[no]** | Display most used languages metrics |
| `plugin_languages_ignored` | `array` *(comma-separated)* **[]** | Languages to ignore |
| `plugin_languages_skipped` | `array` *(comma-separated)* **[]** | Repositories to skip |
| `plugin_languages_limit` | `number` **[8]** *{0 ≤ 𝑥 ≤ 8}* | Maximum number of languages to display |
| `plugin_languages_sections` <sup>🧰</sup> | `array` *(comma-separated)* **[most-used]** *{"most-used", "recently-used"}* | Sections to display |
| `plugin_languages_colors` | `array` *(comma-separated)* **[github]** | Custom languages colors |
| `plugin_languages_aliases` | `string` **[]** | Custom languages names |
| `plugin_languages_details` | `array` *(comma-separated)* **[]** *{"bytes-size", "percentage", "lines"}* | Additional details |
| `plugin_languages_threshold` | `string` **[0%]** | Minimum threshold |
| `plugin_languages_indepth` <sup>🧰</sup> | `boolean` **[false]** | Indepth languages processing (see documentation before enabling) |
| `plugin_languages_analysis_timeout` <sup>🧰</sup> | `number` **[15]** *{1 ≤ 𝑥 ≤ 30}* | Languages analysis timeout |
| `plugin_languages_categories` | `array` *(comma-separated)* **[markup, programming]** *{"data", "markup", "programming", "prose"}* | Language categories to display |
| `plugin_languages_recent_categories` | `array` *(comma-separated)* **[markup, programming]** *{"data", "markup", "programming", "prose"}* | Language categories to display (for recently used section) |
| `plugin_languages_recent_load` | `number` **[300]** *{100 ≤ 𝑥 ≤ 1000}* | Number of events to load (for recently used section) |
| `plugin_languages_recent_days` | `number` **[14]** *{0 ≤ 𝑥 ≤ 365}* | Maximum event age (for recently used section) |
Legend for option icons:
* 🧰 Must be enabled in `settings.json` (for web instances)
<!--/options--> <!--/options-->
*[→ Full specification](metadata.yml)* ## 🔎 `indepth` mode
#### ℹ️ Examples workflows The default algorithm use the top languages provided of each repository you contributed to.
When working in collaborative projects with a lot of people, these numbers may be less representative of your actual work.
The `plugin_languages_indepth` option lets you use a more advanced algorithm for more accurates statistics.
Under the hood, it will clone your repositories, run [linguist-js](https://github.com/Nixinova/Linguist) (a JavaScript port of [GitHub linguist](https://github.com/github/linguist)) and iterate over patches matching your `commits_authoring` setting.
Since git lets you use any email and username for commits, *metrics* may not be able to detect a commit ownership if it isn't the same as your GitHub personal data. By default, it will use your GitHub username, but you can configure additional matching usernames and email addresses using `commits_authoring` option.
*Example: configuring `indepth` mode*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_indepth: yes
commits_authoring: firstname lastname, username, username@users.noreply.github.com
```
> 💡 This feature unlocks the `lines` option in `plugin_languages_details`
> ⚠️ This feature significantly increase workflow time
> ⚠️ Since this mode iterates over **each commit of each repository**, it is not suited for large code base, especially those with a large amount of commits and the ones containing binaries. While `plugin_languages_analysis_timeout` can be used to increase the default timeout for analysis, please be responsible and keep this feature disabled if it cannot work on your account to save GitHub resources and our planet 🌏
> ⚠️ Although *metrics* does not send any code to external sources, repositories are temporarily cloned on the GitHub Action runner. It is advised to keep this option disabled when working with sensitive data or company code. Use at your own risk, *metrics* and its authors **cannot** be held responsible for any resulting code leaks. Source code is available for auditing at [analyzers.mjs](/source/plugins/languages/analyzers.mjs).
> 🌐 Web instances must enable this feature in `settings.json`
## 📅 Recently used languages
This feature uses a similar algorithm as `indepth` mode, but uses patches from your events feed instead.
It will fetch a specified amount of recent push events and perform linguistic analysis on it.
> ⚠️ Note that *metrics* won't be able to use more events than GitHub API is able to provide
*Example: display recently used languages from 400 GitHub events from last 2 weeks*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_sections: recently-used
plugin_languages_recent_load: 400
plugin_languages_recent_days: 14
```
> 🌐 Web instances must enable this feature in `settings.json`
## 🥽 Controling which languages are displayed
Several options lets you customize which languages should be displayed.
It is possible to ignore completely languages or those lower than a given threshold, skip repositories, and filter by language categories.
*Example: hide HTML and CSS languages, skip lowlighter/metrics repository*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_ignored: html, css
plugin_languages_skipped: lowlighter/metrics
```
*Example: hide languages with less than 2% usage*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_threshold: 2%
```
> 💡 The threshold feature will automatically scale remaining languages so the total percentage is always 100%. However, other stats like bytes count and lines are not affected.
When using `indepth` mode, it is possible to hide languages per category.
Supported categories are `data`, `markup`, `programming` and `prose`.
*Example: hide data and prose languages from stats*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_categories: data, prose
plugin_languages_recent_categories: data, prose
```
## 🎨 Using custom colors
The plugin uses GitHub language colors, but it may be hard to distinguish them depending on which languages you use.
It is possible to use custom colors using `plugin_languages_colors` option.
The following syntaxes are supported:
- A predefined set from [colorsets.json](colorsets.json) *(support limited to 8 languages max)*
- `${language}:${color}` to change the color of a language *(case insensitive)*
- `${n}:${color}` to change the color of the the n-th language
Both hexadecimal and [named color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) are supported.
*Example: using a predefined color set*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_colors: rainbow
plugin_languages_limit: 8
```
*Example: setting JavaScript to red, the first language to blue and the second one to `#ff00aa`*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_colors: javascript:red, 0:blue, 1:#ff00aa
```
## ✍️ Using custom languages name
This plugin is limited by [GitHub linguist](https://github.com/github/linguist) capabilities, meaning that some languages may be mislabeled in some cases.
To mitigate this, it is possible to use `plugin_languages_aliases` option and provide a list of overrides using the following syntax: `${language}:${alias}` *(case insensitive)*.
*Example: display JavaScript as JS and TypeScript as TS*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_aliases: javascript:JS typescript:TS
```
## ℹ️ Examples workflows
<!--examples--> <!--examples-->
```yaml
name: Most used
uses: lowlighter/metrics@latest
with:
filename: metrics.plugin.languages.svg
token: ${{ secrets.METRICS_TOKEN }}
base: ''
plugin_languages: 'yes'
plugin_languages_ignored: >-
html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
gnuplot
plugin_languages_limit: 4
```
```yaml
name: Most used (with details)
uses: lowlighter/metrics@latest
with:
filename: metrics.plugin.languages.details.svg
token: ${{ secrets.METRICS_TOKEN }}
base: ''
plugin_languages: 'yes'
plugin_languages_ignored: >-
html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
gnuplot
plugin_languages_details: bytes-size, percentage
plugin_languages_limit: 4
```
```yaml
name: Recently used
uses: lowlighter/metrics@latest
with:
filename: metrics.plugin.languages.recent.svg
token: ${{ secrets.METRICS_TOKEN }}
base: ''
plugin_languages: 'yes'
plugin_languages_ignored: >-
html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
gnuplot
plugin_languages_sections: recently-used
plugin_languages_details: bytes-size, percentage
plugin_languages_limit: 4
```
```yaml
name: Indepth analysis
uses: lowlighter/metrics@latest
with:
filename: metrics.plugin.languages.indepth.svg
token: ${{ secrets.METRICS_TOKEN }}
base: ''
plugin_languages: 'yes'
plugin_languages_ignored: >-
html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
gnuplot
plugin_languages_indepth: 'yes'
plugin_languages_details: lines, bytes-size
plugin_languages_limit: 4
plugin_languages_analysis_timeout: 15
```
<!--/examples--> <!--/examples-->

107
source/plugins/languages/metadata.yml
View File

@@ -1,5 +1,11 @@
name: "🈷️ Most used languages" name: "🈷️ Most used languages"
category: github category: github
description: This plugin can display which languages you use across all repositories you contributed to.
examples:
+indepth analysis (clone and analyze repositories): https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.languages.indepth.svg
+recently used (analyze recent activity events): https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.languages.recent.svg
default algorithm: https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.languages.svg
default algorithm (with details): https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.languages.details.svg
index: 1 index: 1
supports: supports:
- user - user
@@ -9,113 +15,92 @@ scopes:
- public_access - public_access
inputs: inputs:
# Enable or disable plugin
plugin_languages: plugin_languages:
description: Display most used languages metrics description: Enable languages plugin
type: boolean type: boolean
default: no default: no
# List of languages that will be ignored
plugin_languages_ignored: plugin_languages_ignored:
description: Languages to ignore description: Ignored languages
type: array type: array
format: comma-separated format: comma-separated
default: "" default: ""
example: html, css, ... example: html, css, ...
# List of repositories that will be skipped
plugin_languages_skipped: plugin_languages_skipped:
description: Repositories to skip description: Skipped repositories
type: array type: array
format: comma-separated format: comma-separated
default: "" default: ""
example: my-repo-1, my-repo-2, owner/repo-3, ... example: my-repo-1, my-repo-2, owner/repo-3, ...
inherits: repositories_skipped
# Number of languages to display
# Set to 0 to disable limitations
plugin_languages_limit: plugin_languages_limit:
description: Maximum number of languages to display description: Display limit
type: number type: number
default: 8 default: 8
min: 0 min: 0
max: 8 max: 8
zero: disable
# Sections to display plugin_languages_threshold:
plugin_languages_sections: description: Display threshold (percentage)
description: Sections to display type: string
type: array default: 0%
format: comma-separated
default: most-used
example: most-used, recently-used
values:
- most-used # Most used languages
- recently-used # Recently used languages
extras: yes
# Overrides default languages colors
# Use `${n}:${color}` to change the color of the n-th most used language (e.g. "0:red" to make your most used language red)
# Use `${language}:${color}` to change the color of named language (e.g. "javascript:red" to make JavaScript language red, language case is ignored)
# Use a value from `colorsets.json` to use a predefined set of colors
# Both hexadecimal and named colors are supported
# This cannot be used when "plugin_languages_limit" is greater than 8
plugin_languages_colors: plugin_languages_colors:
description: Custom languages colors description: Custom languages colors
type: array type: array
format: format: comma-separated
- comma-separated
- /((?<index>[0-9])|(?<language>[-+a-z0-9#]+)):(?<color>#?[-a-z0-9]+)/
default: github default: github
example: javascript:red, 0:blue, 1:#ff00aa example: javascript:red, 0:blue, 1:#ff00aa
# Overrides default languages name
# Use `${language}:${alias}` to change the name of language (e.g. "javascript:JS" to make JavaScript render as "JS", case of left operand ignored)
plugin_languages_aliases: plugin_languages_aliases:
description: Custom languages names description: Custom languages names
type: string type: string
default: "" default: ""
example: javascript:JS typescript:TS example: javascript:JS typescript:TS
# Languages additional details plugin_languages_sections:
extras: yes
description: Displayed sections
type: array
format: comma-separated
default: most-used
example: most-used, recently-used
values:
- most-used
- recently-used
plugin_languages_details: plugin_languages_details:
extras: yes
description: Additional details description: Additional details
type: array type: array
format: comma-separated format: comma-separated
values: values:
- bytes-size # Languages total size written in bytes - bytes-size
- percentage # Languages proportions in % - percentage
- lines # Estimation of lines of code (plugin_languages_indepth must be enabled) - lines
default: "" default: ""
example: bytes-size, percentage example: bytes-size, percentage
# Minimum threshold (in percentage) to reach for languages to be displayed
plugin_languages_threshold:
description: Minimum threshold
type: string
default: 0%
# Compute indepth languages statistics by cloning repositories and processing your commits individually
# See documentation before enabling
plugin_languages_indepth: plugin_languages_indepth:
description: Indepth languages processing (see documentation before enabling) extras: yes
description: Indepth mode (⚠️ read documentation first)
type: boolean type: boolean
default: false default: false
extras: yes
# Analysis timeout (in minutes)
# In case of timeout, it'll automatically fallback to default algorithm
# Please be nice with GitHub Actions and disable `plugin_languages_indepth` if your account is not supported
# See documentation before enabling
plugin_languages_analysis_timeout: plugin_languages_analysis_timeout:
description: Languages analysis timeout extras: yes
description: Indepth mode - Analysis timeout
type: number type: number
default: 15 default: 15
min: 1 min: 1
max: 30 max: 30
extras: yes
# GitHub language categories to display
plugin_languages_categories: plugin_languages_categories:
description: Language categories to display extras: yes
description: Indepth mode - Displayed categories (most-used section)
type: array type: array
format: comma-separated format: comma-separated
values: values:
@@ -125,9 +110,9 @@ inputs:
- prose - prose
default: markup, programming default: markup, programming
# GitHub language categories to display in recently-used section
plugin_languages_recent_categories: plugin_languages_recent_categories:
description: Language categories to display (for recently used section) extras: yes
description: Indepth mode - Displayed categories (recently-used section)
type: array type: array
format: comma-separated format: comma-separated
values: values:
@@ -137,21 +122,19 @@ inputs:
- prose - prose
default: markup, programming default: markup, programming
# Number of activity events to load (for recently used languages statistics)
# A high number will consume more requests
plugin_languages_recent_load: plugin_languages_recent_load:
description: Number of events to load (for recently used section) extras: yes
description: Events to load (recently-used section)
type: number type: number
default: 300 default: 300
min: 100 min: 100
max: 1000 max: 1000
# Filter events by age (for recently used languages statistics)
# Set to 0 to disable age filtering
# Note that metrics won't be able to load more events than GitHub is able to provide
plugin_languages_recent_days: plugin_languages_recent_days:
description: Maximum event age (for recently used section) extras: yes
description: Events maximum age (day, recently-used section)
type: number type: number
default: 14 default: 14
min: 0 min: 0
max: 365 max: 365
zero: disable