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

docs: improve overall documentation

Browse Source
This commit is contained in:
lowlighter
2022-01-15 00:12:18 -05:00
parent ee1abadf9a
commit c0f4cf42ad
21 changed files with 162 additions and 236 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
.github/readme/partials/documentation/contributing.md vendored
View File

@@ -1,12 +1,14 @@
## 💪 Customizing and contributing
## 💪 Contributing
Metrics is built to be easily customizable.
Fork this repository, switch used action from `lowlighter/metrics@latest` to your fork and start coding!
If you are interested in contributing, the following resources may interest you:
See [ARCHITECTURE.md](/ARCHITECTURE.md) for more informations about how code is structured.
* [💪 Contribution guide](/CONTRIBUTING.md)
* [🧬 Architecture](/ARCHITECTURE.md)
* [📜 License](/LICENSE)
* **:octocat: GitHub resources**
* [📖 GitHub GraphQL API](https://docs.github.com/en/graphql)
* [📖 GitHub GraphQL Explorer](https://docs.github.com/en/free-pro-team@latest/graphql/overview/explorer)
* [📖 GitHub Rest API](https://docs.github.com/en/rest)
* [📖 GitHub Octicons](https://github.com/primer/octicons)
To report a bug fill an [issue](https://github.com/lowlighter/metrics/issues) describing it.
To suggest new features or requesting help to setup metrics, check out [discussions](https://github.com/lowlighter/metrics/discussions).
If you want to contribute, submit a [pull request](https://github.com/lowlighter/metrics/pulls).
Be sure to read [CONTRIBUTING.md](/CONTRIBUTING.md) for more information about this.
Use [`💬 discussions`](https://github.com/lowlighter/metrics/discussions) for feedback, new features suggestions, bugs reports or to request help for installation.

10
.github/readme/partials/documentation/inspirations.md vendored Normal file
View File

@@ -0,0 +1,10 @@
# ✨ Inspirations
* [anuraghazra/github-readme-stats](https://github.com/anuraghazra/github-readme-stats)
* [jstrieb/github-stats](https://github.com/jstrieb/github-stats)
* [ankurparihar/readme-pagespeed-insights](https://github.com/ankurparihar/readme-pagespeed-insights)
* [jasonlong/isometric-contributions](https://github.com/jasonlong/isometric-contributions)
* [jamesgeorge007/github-activity-readme](https://github.com/jamesgeorge007/github-activity-readme)
* [vvo/sourcekarma](https://github.com/vvo/sourcekarma)
* [ryo-ma/github-profile-trophy](https://github.com/ryo-ma/github-profile-trophy)
* [teoxoy/profile-readme-stats](https://github.com/teoxoy/profile-readme-stats)

40
.github/readme/partials/documentation/organizations.md vendored
View File

@@ -1,19 +1,41 @@
### 🏦 Organizations metrics
# 🏦 Organizations metrics
While metrics targets mainly user accounts, it's possible to render metrics for organization accounts.
![Metrics (organization account)](https://github.com/lowlighter/lowlighter/blob/master/metrics.organization.svg)
<details>
<summary><b>💬 Metrics for organizations</b> <i>(click to expand)</i></summary>
## 💬 Metrics for organizations
<%- await include(`/partials/documentation/organizations/setup.md`) -%>
Setup is the same as for user accounts, though you'll need to add `read:org` scope, **whether you're member of target organization or not**.
</details>
![Add read:org scope to personal token](/.github/readme/imgs/setup_token_org_read_scope.png)
<details>
<summary><b>💬 Organizations memberships for user accounts</b> <i>(click to expand)</i></summary>
You'll also need to set `user` option with your organization name.
<%- await include(`/partials/documentation/organizations/memberships.md`) -%>
If you're encounting errors and your organization is using single sign-on, try to [authorize your personal token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on).
Most of plugins supported by user accounts will work with organization accounts, but note that rendering metrics for organizations consume way more APIs requests.
To support private repositories, add full `repo` scope to your personal token.
### ℹ️ Example workflow
```yaml
- uses: lowlighter/metrics@latest
with:
# ... other options
token: ${{ secrets.METRICS_TOKEN }} # A personal token from an user account with read:org scope
user: organization-name # Organization name
```
### 💬 Organizations memberships for user accounts
Only public memberships can be displayed by metrics by default.
You can manage your membership visibility in the `People` tab of your organization:
![Publish organization membership](/.github/readme/imgs/setup_public_membership_org.png)
For organization memberships, add `read:org` scope to your personal token.
![Add read:org scope to personal token](/.github/readme/imgs/setup_token_org_read_scope.png)
</details>

12
.github/readme/partials/documentation/organizations/memberships.md vendored
View File

@@ -1,12 +0,0 @@
<!-- <% if (false) { %> -->
#### 💬 Organizations memberships for user accounts
<!-- <% } %> -->
Only public memberships can be displayed by metrics by default.
You can manage your membership visibility in the `People` tab of your organization:
![Publish organization membership](/.github/readme/imgs/setup_public_membership_org.png)
For organization memberships, add `read:org` scope to your personal token.
![Add read:org scope to personal token](/.github/readme/imgs/setup_token_org_read_scope.png)

25
.github/readme/partials/documentation/organizations/setup.md vendored
View File

@@ -1,25 +0,0 @@
<!-- <% if (false) { %> -->
#### 💬 Metrics for organizations
<!-- <% } %> -->
Setup is the same as for user accounts, though you'll need to add `read:org` scope, **whether you're member of target organization or not**.
![Add read:org scope to personal token](/.github/readme/imgs/setup_token_org_read_scope.png)
You'll also need to set `user` option with your organization name.
If you're encounting errors and your organization is using single sign-on, try to [authorize your personal token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on).
Most of plugins supported by user accounts will work with organization accounts, but note that rendering metrics for organizations consume way more APIs requests.
To support private repositories, add full `repo` scope to your personal token.
#### ℹ️ Example workflow
```yaml
- uses: lowlighter/metrics@latest
with:
# ... other options
token: ${{ secrets.METRICS_TOKEN }} # A personal token from an user account with read:org scope
user: organization-name # Organization name
```

14
.github/readme/partials/documentation/plugins.md vendored
View File

@@ -1,19 +1,15 @@
## 🧩 Plugins
Plugins are features which provide additional content and lets you customize your rendered metrics.
See their respective documentation for more informations about how to setup them.
Plugins provide additional content and lets you customize your rendered metrics.
The following plugins are maintained by Metric's core team:
* **📦 Maintained by core team**
<% { let previous = null; for (const [plugin, {name, category, authors = []}] of Object.entries(plugins).filter(([key, value]) => (value)&&(value.category !== "community")).sort(([an, a], [bn, b]) => a.category === b.category ? an.localeCompare(bn) : 0)) { %>
<% if (previous !== category) { previous = category -%>
* **<%= `${category.charAt(0).toLocaleUpperCase()}${category.substring(1)}` %>**
* **<%= `${category.charAt(0).toLocaleUpperCase()}${category.substring(1)}` %>**
<% } -%>
* [<%- name %>](/source/plugins/<%= plugin %>/README.md)<%# -%>
* [<%- name %>](/source/plugins/<%= plugin %>/README.md)<%# -%>
<% }} %>
### 🎲 Community plugins
The following plugins are provided and maintained by Metrics's user community:
* **🎲 Maintained by community**
<% { let previous = null; for (const [plugin, {name, category, authors = []}] of Object.entries(plugins).filter(([key, value]) => (value)&&(value.category === "community")).sort(([an, a], [bn, b]) => a.category === b.category ? an.localeCompare(bn) : 0)) { %><%# -%>
* [<%- name %>](/source/plugins/<%= plugin %>/README.md) by <%- authors.map(author => `[@${author}](https://github.com/${author})`).join(" ") %>
<% }} %>

19
.github/readme/partials/documentation/setup.md vendored Normal file
View File

@@ -0,0 +1,19 @@
## 🦮 Setup
There are several ways to setup metrics, each having its advantages and disadvantages:
* [⚙️ Using GitHub Action on a profile repository *(~10 min)*](/.github/readme/partials/setup/action.md)
* ✔️ All features
* ✔️ High availability (no downtimes)
* ➖ Configuration can be a bit time-consuming
* [💕 Using the shared instance *(~1 min)*](/.github/readme/partials/setup/shared.md)
* ✔️ Easily configurable and previewable
* ➖ Limited features *(compute-intensive features are disabled)*
* 🐳 Using command line with docker *(~5 min)* *(documentation not available yet)*
* ✔️ Suited for one-time rendering
* [🏗️ Deploying your own web instance *(~20 min)*](/.github/readme/partials/setup/web.md)
* ➖ Mostly intended for development, or to create another shared instance
Additional resources for setup:
* [🏦 Configuring metrics for organizations](/.github/readme/partials/organizations.md)
* [🧰 Template/Plugin compatibility matrix](/.github/readme/partials/compatibility.md)

115
.github/readme/partials/documentation/setup/action.md vendored Normal file
View File

@@ -0,0 +1,115 @@
# ⚙️ Using GitHub Action on a profile repository (~10 min setup)
Setup a GitHub Action which runs periodically and pushes generated images to a repository.
Assuming your username is `my-github-user`, you can then embed rendered metrics in your readme like below:
```markdown
<!-- If you're using "master" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg)
<!-- If you're using "main" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/main/github-metrics.svg)
```
## 💬 How to setup?
### 0. Setup a personal repository
Create a repository with the same name as your GitHub login (if it's not already done).
![Setup personal repository](/.github/readme/imgs/setup_personal_repository.png)
Its `README.md` will be displayed on your user profile:
![GitHub Profile Example](/.github/readme/imgs/example_github_profile.png)
### 1. Create a GitHub personal token
From the `Developer settings` of your account settings, select `Personal access tokens` to create a new token.
No additional scopes are needed for basic metrics, but you may have to grant additional scope depending on what features you're planning to use:
- `public_repo` scope for some plugins
- `read:org` scope for all organizations related metrics
- `repo` scope for all private repositories related metrics
- `read:user` scope may also be required for some private repositories related metrics
![Setup a GitHub personal token](/.github/readme/imgs/setup_personal_token.png)
A scope-less token can still display private contributions by enabling `Include private contributions on my profile` in your account settings:
![Enable "Include private contributions on my profile`"](/.github/readme/imgs/setup_private_contributions.png)
If a plugin has not enough scopes to operate (and `plugins_errors_fatal` isn't enabled), it'll be reported in the rendering like below:
![Plugin error example](https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.error.svg)
### 2. Put your GitHub personal token in your repository secrets
Go to the `Settings` of your repository to create a new secret and paste your freshly generated GitHub token there.
![Setup a repository secret](/.github/readme/imgs/setup_repository_secret.png)
### 3. Create a GitHub Action workflow in your repository
Create a new workflow from the `Actions` tab of your repository and paste the following:
```yaml
name: Metrics
on:
# Schedule updates (each hour)
schedule: [{cron: "0 * * * *"}]
# Lines below let you run workflow manually and on each commit (optional)
workflow_dispatch:
push: {branches: ["master", "main"]}
jobs:
github-metrics:
runs-on: ubuntu-latest
steps:
# See action.yml for all options
- uses: lowlighter/metrics@latest
with:
# Your GitHub token
token: ${{ secrets.METRICS_TOKEN }}
```
See all supported options in [action.yml](/action.yml).
Rendered metrics will be committed to your repository on each run.
![Action update example](/.github/readme/imgs/example_action_update.png)
#### Choosing between `@latest`, `@master` or a fork
If you wish to use new features as they're being released, you can switch from `@latest` to `@master`.
As the latter is used as a development branch, jobs may fail from time to time (although we try to mitigate this).
For convenience, it is possible to use `@main` instead of `@master`.
When using a token with additional permissions, it is advised to fork this repository and use it instead to minimize security risks:
```yaml
- uses: my-github-username/metrics@master
# If you make changes on your fork, be sure not leave @latest as tag!
```
In this case, please consider watching new releases to stay up-to-date and enjoy latest features!
`@latest` will be updated on each release. Metrics doesn't introduce breaking changes **from an user point of view** (i.e. your workflows will always be valid) so you can follow release cycles without worrying.
#### Examples workflows
Metrics displayed on this page are rendered from this [workflow](https://github.com/lowlighter/lowlighter/blob/master/.github/workflows/metrics.yml) so you can check it out for some code examples about plugins usage.
You can also take a look at this [user workflow](https://github.com/lowlighter/lowlighter/blob/master/.github/workflows/personal.yml) if you want.
### 4. Embed link into your README.md
Update your README.md to embed your metrics:
```markdown
<!-- If you're using "master" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg)
<!-- If you're using "main" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/main/github-metrics.svg)
<!-- If you're using the "columns" display mode -->
<img src="https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg" alt="Metrics" width="100%">
```

19
.github/readme/partials/documentation/setup/shared.md vendored Normal file
View File

@@ -0,0 +1,19 @@
# 💕 Using the shared instance (~1 min setup, but with limitations)
For convenience, you can use the shared instance available at [metrics.lecoq.io](https://metrics.lecoq.io) without any additional setup.
```markdown
![Metrics](https://metrics.lecoq.io/my-github-user)
```
This is mostly intended for previews, to enjoy all features consider using GitHub Action instead.
Availability is not guaranteed.
To ensure service availability, shared instance has a few limitations:
* Images are cached for 1 hour
* Rendered metrics **won't be updated** during this time window when queried
* You can manually update rendering again your metrics on [metrics.lecoq.io](https://metrics.lecoq.io)
* A rate limiter is enabled to prevent denial of service (it doesn't affect already cached metrics)
* Some plugins may not be available
Service is provided free of charge, so please be gentle with it 🙂

142
.github/readme/partials/documentation/setup/web.md vendored Normal file
View File

@@ -0,0 +1,142 @@
# 🏗️ Deploying your own web instance (~20 min setup, depending on your sysadmin knowledge)
Setup a metrics instance on your server if you don't want to use GitHub Actions and [metrics.lecoq.io](https://metrics.lecoq.io).
See all supported options in [settings.example.json](/settings.example.json).
Assuming your username is `my-github-user`, you can then embed rendered metrics in your readme like below:
```markdown
![Metrics](https://my-personal-domain.com/my-github-user)
```
## 💬 How to setup?
### 0. Prepare your server
You'll need a server with a recent version of [Docker](https://www.docker.com/).
### 1. Create a GitHub personal token
From the `Developer settings` of your account settings, select `Personal access tokens` to create a new token.
No additional scopes are needed.
![Setup a GitHub personal token](/.github/readme/imgs/setup_personal_token.png)
### 2. Configure your instance
Fetch [settings.example.json](/settings.example.json) which contains all supported option.
```shell
wget https://raw.githubusercontent.com/lowlighter/metrics/master/settings.example.json
```
Edit `settings.json` to configure your instance.
```javascript
{
//GitHub API token
"token":"GITHUB_TOKEN",
//Other options...
}
```
If you plan to make your web instance public, it is advised to restrict its access thanks to rate limiter and access list.
### 3. Start docker container
Metrics docker images are published on [GitHub Container Registry](https://github.com/lowlighter/metrics/pkgs/container/metrics).
Configure the following variables (or hardcode them in the command in the next block):
```shell
# Select an existing docker image tag
VERSION=latest
# Path to configured `settings.json`
SETTINGS=/path/to/settings.json
# Port used internally (use the same one than in `settings.json`)
SERVICE_PORT=3000
# Port to publish
PUBLISHED_PORT=80
```
And start the container using the following command:
```shell
docker run -d --workdir=/metrics --entrypoint="" -p=127.0.0.1:$PUBLISHED_PORT:$SERVICE_PORT --volume=$SETTINGS:/metrics/settings.json ghcr.io/lowlighter/metrics:$VERSION npm start
```
### 4. Embed link into your README.md
Edit your repository readme and add your metrics image from your server domain:
```markdown
![Metrics](https://my-personal-domain.com/my-github-user)
```
### 5. (optional) Setup your instance as a service
To ensure that your instance will restart if it reboots or crashes, you should set it up as a service.
This is described below for Linux-like systems which support *systemd*.
Create a new service file `/etc/systemd/system/github_metrics.service` and paste the following after editing paths inside:
```ini
[Unit]
Description=Metrics
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
ExecStart=(command to run as service)
[Install]
WantedBy=multi-user.target
```
Reload services, enable it, start it and check if it is up and running:
```shell
systemctl daemon-reload
systemctl enable github_metrics
systemctl start github_metrics
systemctl status github_metrics
```
### Alternative option: run an instance locally (intended for testing and development)
To run an instance without docker, you'll need to have [NodeJS](https://nodejs.org) (see used version in [Dockerfile](/Dockerfile#L1-L2)) installed.
Clone repository, install dependencies and copy configuration example to `settings.json`:
```shell
git clone https://github.com/lowlighter/metrics.git
cd metrics/
npm install --only=prod
cp settings.example.json settings.json
```
Once you've finished configuring metrics, start your instance using the following command:
```shell
npm start
```
You should now be able to access your server with provided port in `setting.json` from your browser.
## 🔗 HTTP parameters
Most of options from [action.yml](/action.yml) are actually supported by web instance, though syntax is slightly different.
All underscores (`_`) must be replaced by dots (`.`) and `plugin_` prefixes must be dropped.
For example, to configure pagespeed plugin you'd use the following:
```
https://my-personal-domain.com/my-github-user?pagespeed=1&pagespeed.detailed=1&pagespeed.url=https%3A%2F%2Fexample.com
```
Note that url parameters must be [encoded](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/encodeURIComponent).
As for `base` content, which is enabled by default, sections are available through "`base.<section>`".
For example, to display only `repositories` section, use:
```
https://my-personal-domain.com/my-github-user?base=0&base.repositories=1
```

2
.github/readme/partials/documentation/templates.md vendored
View File

@@ -1,7 +1,7 @@
## 🖼️ Templates
Templates lets you change general appearance of rendered metrics.
See their respective documentation for more informations about how to setup them:
<% for (const [template, {name}] of Object.entries(templates).filter(([key, value]) => value)) { %>
* [<%- name %>](/source/templates/<%= template %>/README.md)<%# -%>
<% } %>