docs: improve overall documentation

Author: lowlighter

.github/readme/README.md

@@ -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`) %>
 <% } %>

.github/readme/partials/documentation.md

@@ -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`) -%>
 <% } %>

.github/readme/partials/documentation/contributing.md

@@ -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.

.github/readme/partials/references.md …e/partials/documentation/inspirations.md.github/readme/partials/references.md renamed to .github/readme/partials/documentation/inspirations.md .github/readme/partials/references.md renamed to .github/readme/partials/documentation/inspirations.md

@@ -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)

.github/readme/partials/documentation/organizations.md

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

.github/readme/partials/documentation/organizations/memberships.md

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

.github/readme/partials/documentation/organizations/setup.md

@@ -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)

.github/readme/partials/documentation/plugins.md

@@ -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).