From 11eb8607a2305eecf27cbeb31a301c6cc419982e Mon Sep 17 00:00:00 2001
From: Mahyar Mirrashed <mah.mirr@gmail.com>
Date: Fri, 20 Dec 2024 02:33:17 -0600
Subject: [PATCH] docs: add set up information

---
 README.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 94 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 0d5d594..9be96ca 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,97 @@
-# GitHub Readme Stats
+# GitHub Readme Stats 📊
 
-This project builds upon the previous work by Jainam Desai[^1] and leverages the
-Google GitHub Go module[^2] for enhanced functionality.
+This project builds upon the previous work by Jainam Desai[^1]. Please consider
+starring this repository if you found it useful! ⭐️
+
+## Installation
+
+To integrate this action into your repository, you'll need to start by creating
+a GitHub Action workflow file. In your repository, navigate to/create
+`.github/workflows/update-readme.yaml`.
+
+```yaml
+name: Update Readme
+
+on:
+  schedule:
+    - cron: "1 3 * * *" # best to run at random time of day
+  workflow_dispatch:
+
+jobs:
+  Update:
+    name: Update Stats
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: mahyarmirrashed/github-readme-stats@main # v1.0 and other tags exist, as well
+        with:
+          GITHUB_TOKEN: ${{ secrets.PAT }}
+          TIMEZONE: "America/Winnipeg"
+          INCLUDES:
+            "--include DAY_STATS --include WEEK_STATS --include LANGUAGE_STATS"
+```
+
+You will need to generate a Personal Access Token (PAT) in your
+[GitHub Settings Page](https://github.com/settings/tokens). There, select the
+`Generate new token: fine-grained, repo-scoped` option.
+
+Give your token a name (e.g. "Profile Stats"), an expiration (e.g. 30 days), and
+a description. For the permissions, you need to give access to "All
+repositories", and selecting "read-only" "Content" access for the "Repository
+Permissions". Then, generate the token.
+
+Once the token is generated, copy it, and create a new repository secret for
+your repository. They will be located at an address like
+`https://github.com/<user>/<repo>/settings/secrets/actions`. There, create a new
+repository secret, name it `PAT`, and paste the generated token in the body!
+
+> [!WARNING]  
+> Generally, it is not safe to give such encompassing permissions for a Personal
+> Access Token, like `read` permissions for all repositories. However, there is
+> <ins>no other way</ins> to get the statistics you desire without this
+> permission.
+>
+> I created this GitHub action to keep the processing of this information local
+> to GitHub's infrastructure (unlike WakaTime[^2] to reduce potential attack
+> surfaces.
+
+## Usage
+
+This action operates by updating a specific section in your `README.md` file.
+
+### Adding the Markers
+
+Insert the following markers where you want the statistics to appear:
+
+```markdown
+<!-- README-STATS:START -->
+
+<!-- README-STATS:END -->
+```
+
+When the GitHub Action runs, it will populate the section between these markers
+with your chosen statistics.
+
+## Configuration
+
+You can customize the statistics included and their order by modifying the
+`INCLUDES` parameter in your workflow file.
+
+### Available Includes
+
+- `DAY_STATS`: Commit statistics based on the time of day.
+- `WEEK_STATS`: Commit statistics based on the day of the week.
+- `LANGUAGE_STATS`: Programming language usage statistics.
+
+## Troubleshooting
+
+- **README.md Not Found:** Ensure that README.md exists in the root of your
+  repository and that you’ve added the <!-- README-STATS:START --> and
+  <!-- README-STATS:END --> markers.
+- **Permissions Error:** Verify that your PAT has the necessary scopes (repo and
+  read:user).
+- **Incorrect Timezone:** Make sure the timezone string is valid (e.g.,
+  "America/Winnipeg").
 
 ## Contributions
 
@@ -10,4 +100,4 @@ enhancements or bug fixes.
 
 [^1]: https://github.com/th3c0d3br34ker/github-readme-info
 
-[^2]: https://github.com/google/go-github
+[^2]: https://wakatime.com/plugins/status?onboarding=true