docs: improve overall documentation

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

View File

@@ -2,6 +2,6 @@
[![Build, test, analyze and publish](https://github.com/lowlighter/metrics/actions/workflows/workflow.yml/badge.svg)](https://github.com/lowlighter/metrics/actions/workflows/workflow.yml) [![Metrics (examples)](https://github.com/lowlighter/lowlighter/actions/workflows/metrics.yml/badge.svg)](https://github.com/lowlighter/lowlighter/actions/workflows/metrics.yml)
<% for (const partial of ["introduction", "features", "setup", "documentation", "license", "references"]) { -%>
<% for (const partial of ["introduction", "documentation", "license"]) { -%>
<%- await include(`/partials/${partial}.md`) %>
<% } %>

View File

@@ -1,5 +1,9 @@
# 📚 Documentation
<% for (const partial of ["compatibility", "templates", "plugins", "organizations", "contributing"]) { %>
<% if (/[.]0-beta$/.test(packaged.version)) { %>
> <sup>*⚠️ This is the documentation of **v<%= packaged.version.replace(/[.]0-beta$/, "") %>-beta** (`@master`/`@main` branches) which includes [unreleased features](https://github.com/lowlighter/metrics/compare/latest...master). See documentation for [**v<%= (Number(packaged.version.replace(/[.]0-beta$/, ""))-0.01).toFixed(2).replace(/[.]0/, ".") %>** (`@latest` branch) here](https://github.com/lowlighter/metrics/blob/latest/README.md).*</sup>
<% } %>
<% for (const partial of ["setup", "templates", "plugins", "contributing"]) { %>
<%- await include(`/partials/documentation/${partial}.md`) -%>
<% } %>

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.

View File

@@ -1,12 +1,4 @@
## 📖 Useful references
* [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)
* See [GitHub Logos and Usage](https://github.com/logos) for more information.
### ✨ Inspirations
# ✨ Inspirations
* [anuraghazra/github-readme-stats](https://github.com/anuraghazra/github-readme-stats)
* [jstrieb/github-stats](https://github.com/jstrieb/github-stats)

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>

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)

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
```

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)<%# -%>
<% }} %>
### 🎲 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(" ") %>
<% }} %>

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)

View File

@@ -1,8 +1,19 @@
<!-- <% if (false) { %> -->
#### 💬 How to setup?
<!-- <% } %> -->
# ⚙️ Using GitHub Action on a profile repository (~10 min setup)
### 0. Setup your personal repository
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).

View File

@@ -1,6 +1,13 @@
<!-- <% if (false) { %> -->
#### 💬 Fair use
<!-- <% } %> -->
# 💕 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

View File

@@ -1,6 +1,15 @@
<!-- <% if (false) { %> -->
#### 💬 How to setup?
<!-- <% } %> -->
# 🏗️ 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
@@ -112,3 +121,22 @@ 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
```

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)<%# -%>
<% } %>

View File

@@ -1,35 +0,0 @@
## 🦑 Interested to get your own?
For a fully-featured experience you should use **metrics** as a [GitHub Action](https://github.com/marketplace/actions/metrics-embed), but you can also try it now at [metrics.lecoq.io](https://metrics.lecoq.io/) with your GitHub username!
Choose `📊 Metrics embed` if you want to customize your GitHub profile and `✨ Metrics insights` to get a quick overview of your GitHub statistics:
<table>
<tr>
<th><a href="https://metrics.lecoq.io">📊 Metrics embed</a></th>
<th><a href="https://metrics.lecoq.io/about">✨ Metrics insights</a></th>
</tr>
<tr>
<td align="center">
Embed metrics images on your profile readme or blog!<br>
Use GitHub actions for even more features!<br>
<img src="/.github/readme/imgs/features_embed.gif" width="441">
</td>
<td align="center">
Share your metrics with friends and on social medias!<br>
No configuration needed!<br>
<img src="/.github/readme/imgs/features_insights.gif" width="441">
</td>
</tr>
</table>
### 🐙 Features
* Create infographics from **<%= Object.entries(plugins).filter(([key, value]) => (value)&&(!["base", "core"].includes(key))).length %> plugins**, **<%= Object.entries(templates).filter(([key, value]) => (value)&&(!["community"].includes(key))).length %> templates** and **<%= Object.entries(descriptor.inputs).length %> options**
* Even more **customization** with [community templates](source/templates/community) or by [forking this repository](https://github.com/lowlighter/metrics/network/members) and editing HTML/CSS/EJS
* Support **users**, **organizations** and even **repositories**
* Transparent by default so it'll blend well whether light or dark mode is used
* Save your metrics as **images** (SVG, PNG or JPEG), **markdown**, **PDF** or **JSON**
* Upload them to GitHub through commits, pull requests and gists, or handle renders yourself
* Works either as [GitHub action](https://github.com/marketplace/actions/metrics-embed) or as [web instance](https://metrics.lecoq.io)

View File

@@ -1,8 +1,4 @@
Generate your metrics that you can embed everywhere, including your GitHub profile readme! It works for both user and organization accounts, and even for repositories!
<% if (/[.]0-beta$/.test(packaged.version)) { %>
> <sup>*⚠️ This is the documentation of **v<%= packaged.version.replace(/[.]0-beta$/, "") %>-beta** (`@master` branch) which includes [unreleased features](https://github.com/lowlighter/metrics/compare/latest...master), see documentation of [**v<%= (Number(packaged.version.replace(/[.]0-beta$/, ""))-0.01).toFixed(2).replace(/[.]0/, ".") %>** (`@latest` branch) here](https://github.com/lowlighter/metrics/blob/latest/README.md).*</sup>
<% } %>
Generate metrics that can be embedded everywhere, including your GitHub profile readme! For users, organizations, and even repositories!
<table>
<tr>
@@ -12,18 +8,13 @@ Generate your metrics that you can embed everywhere, including your GitHub profi
<tr>
<%- plugins.base.readme.demo?.replace(/<img src=/g, `<img alt="" width="400" src=`) %>
</tr>
</table>
<% {
let cell = 0
const elements = Object.entries(plugins).filter(([key, value]) => (value)&&(!["base", "core"].includes(key)&&(value.category !== "community")))
%>
And you can customize these heavily with plugins, templates and hundreds of options!
<table>
-%>
<tr>
<th colspan="2" align="center">
<a href="source/plugins/README.md">🧩 <%= elements.length %>+ plugins</a>
<a href="/source/plugins/README.md">🧩 Customizable with <%= Object.entries(plugins).filter(([key, value]) => (value)&&(!["base", "core"].includes(key))).length %> plugins and <%= Object.entries(descriptor.inputs).length %> options!</a>
</th>
</tr>
<% if (elements.length%2)
@@ -48,19 +39,17 @@ And you can customize these heavily with plugins, templates and hundreds of opti
<% }}} -%>
<tr>
<th colspan="2" align="center">
<a href="https://github.com/lowlighter/metrics#-community-plugins">🎲 Community plugins</a>
<a href="/#-plugins">🎲 See also community plugins</a>
</th>
</tr>
</table>
<% } %>
<% {
let cell = 0
const elements = Object.entries(templates).filter(([key, value]) => (value)&&(!["community"].includes(key)))
%>
<table>
-%>
<tr>
<th colspan="2" align="center">
<a href="source/templates/README.md">🖼️ <%= elements.length %>+ templates</a>
<a href="/source/templates/README.md">🖼️ And even more with <%= elements.length %>+ templates!</a>
</th>
</tr>
<% if (elements.length%2)
@@ -71,7 +60,7 @@ And you can customize these heavily with plugins, templates and hundreds of opti
if (cell === "even") {
-%>
<tr>
<% } %> <th><a href="source/templates/<%= template %>/README.md"><%- name -%></a></th>
<% } %> <th><a href="/source/templates/<%= template %>/README.md"><%- name -%></a></th>
<% if (cell === "odd") {
-%> </tr>
<% }}
@@ -84,10 +73,32 @@ And you can customize these heavily with plugins, templates and hundreds of opti
-%> </tr>
<% }}} -%>
<tr>
<th colspan="2"><a href="source/templates/community/README.md"><%= templates.community.name -%></a></th>
<th colspan="2"><a href="/source/templates/community/README.md">📕 See also community templates</a></th>
</tr>
<tr>
<%- templates.community.readme.demo %>
<th colspan="2"><h2>🦑 Try it now!</h2></th>
</tr>
<tr>
<th><a href="https://metrics.lecoq.io">📊 Metrics embed</a></th>
<th><a href="https://metrics.lecoq.io/about">✨ Metrics insights</a></th>
</tr>
<tr>
<td align="center">
Embed metrics images on your profile or blog!<br>
Use <a href="https://github.com/marketplace/actions/metrics-embed">GitHub actions</a> for even more features!<br>
<img src="/.github/readme/imgs/features_embed.gif" width="441">
</td>
<td align="center">
Share your metrics with friends and on social medias!<br>
No configuration needed!<br>
<img src="/.github/readme/imgs/features_insights.gif" width="441">
</td>
</tr>
<tr>
<td align="center" colspan="2">
<b>Power user?</b><br>
<a href="https://github.com/lowlighter/metrics/fork">Fork this repository</a> and edit HTML, CSS, JS and <a href="https://github.com/mde/ejs"> for even more customization!
</td>
</tr>
</table>
<% } %>

View File

@@ -5,12 +5,5 @@ MIT License
Copyright (c) 2020-present lowlighter
```
![License details](https://github.com/lowlighter/lowlighter/blob/master/metrics.licenses.svg)
See full license in [LICENSE.md](/LICENSE.md)
![Sponsors](https://github.com/lowlighter/lowlighter/blob/master/metrics.sponsors.svg)
![Contributors](https://github.com/lowlighter/lowlighter/blob/master/metrics.contributors.svg)
[`♥️ Become a sponsor`](https://github.com/sponsors/lowlighter)

View File

@@ -1,5 +0,0 @@
# 📜 How to use?
<% for (const partial of ["action", "shared", "web"]) { -%>
<%- await include(`/partials/setup/${partial}.md`) %>
<% } %>

View File

@@ -1,20 +0,0 @@
## ⚙️ Using GitHub Action on your profile repository (~5 min setup)
Setup a GitHub Action which runs periodically and pushes your generated metrics image to your repository.
See all supported options in [action.yml](/action.yml).
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)
```
<details>
<summary><b>💬 How to setup?</b> <i>(click to expand)</i></summary>
<%- await include(`/partials/setup/action/setup.md`) -%>
</details>

View File

@@ -1,17 +0,0 @@
## 💕 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.
<details>
<summary><b>💬 Fair use</b> <i>(click to expand)</i></summary>
<%- await include(`/partials/setup/shared/usage.md`) -%>
</details>

View File

@@ -1,25 +0,0 @@
## 🏗️ Deploying your own web instance (~15 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)
```
<details>
<summary><b>💬 How to setup?</b> <i>(click to expand)</i></summary>
<%- await include(`/partials/setup/web/setup.md`) -%>
</details>
<details>
<summary><b>🔗 HTTP parameters</b> <i>(click to expand)</i></summary>
<%- await include(`/partials/setup/web/http.md`) -%>
</details>

View File

@@ -1,20 +0,0 @@
<!-- <% if (false) { %> -->
#### 🔗 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
```