Skip to content

Commit 9ce9bde

Browse files
committed
docs: improve docs and fix tests
1 parent aac13f5 commit 9ce9bde

File tree

3 files changed

+42
-47
lines changed

3 files changed

+42
-47
lines changed

readme.md

Lines changed: 29 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -216,7 +216,7 @@ You can use [GitHub's theme context](https://github.blog/changelog/2021-11-24-sp
216216
##### Use GitHub's new media feature
217217

218218
You can use [GitHub's new media feature](https://github.blog/changelog/2022-05-19-specify-theme-context-for-images-in-markdown-beta/) in HTML to specify whether to display images for light or dark themes. This is done using the HTML `<picture>` element in combination with the `prefers-color-scheme` media feature.
219-
219+
220220
```html
221221
<picture>
222222
<source
@@ -309,8 +309,8 @@ You can provide multiple comma-separated values in the bg_color option to render
309309
- `custom_title` - Sets a custom title for the card _(string)_. Default `Most Used Languages`.
310310
- `disable_animations` - Disables all animations in the card _(boolean)_. Default: `false`.
311311
- `hide_progress` - It uses the compact layout option, hides percentages, and removes the bars. Default: `false`.
312-
- `p` - Configures ranking algorithm, defaults to 1, recommended is 0.5 _(number)_
313-
- `q` - Configures ranking algorithm, defaults to 0, recommended is 0.5 _(number)_
312+
- `p` - Configures language stats algorithm _(number)_ (see [Language stats algorithm](#Language-stats-algorithm)), defaults to 1.
313+
- `q` - Configures language stats algorithm _(number)_ (see [Language stats algorithm](#Language-stats-algorithm)), defaults to 0.
314314

315315
> **Warning**
316316
> Language names should be URI-escaped, as specified in [Percent Encoding](https://en.wikipedia.org/wiki/Percent-encoding)
@@ -347,26 +347,6 @@ Endpoint: `api/pin?username=anuraghazra&repo=github-readme-stats`
347347
[![Readme Card](https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats)](https://github.com/anuraghazra/github-readme-stats)
348348
```
349349

350-
### Ranking configuration
351-
352-
You can use the `&p=` and `&q=` options to change the method used to rank the languages used. The values must be positive real numbers.
353-
354-
The algorithm used is
355-
356-
```javascript
357-
ranking_index = (byte_count ^ p) * (repo_count ^ q)
358-
```
359-
360-
[Details here.](https://github.com/anuraghazra/github-readme-stats/issues/1600#issuecomment-1046056305)
361-
362-
- `&p=1&q=0` - _(default)_ Orders by byte count
363-
- `&p=0.5&q=0.5` - _(recommended)_ Uses both byte and repo count for ranking
364-
- `&p=0&q=1` - Orders by repo count
365-
366-
```md
367-
[![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&p=0.5&q=0.5)](https://github.com/anuraghazra/github-readme-stats)
368-
```
369-
370350
### Demo
371351

372352
[![Readme Card](https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats)](https://github.com/anuraghazra/github-readme-stats)
@@ -382,6 +362,23 @@ The top languages card shows a GitHub user's most frequently used top language.
382362
> **Note**
383363
> Top Languages does not indicate my skill level or anything like that; it's a GitHub metric to determine which languages have the most code on GitHub. It is a new feature of github-readme-stats.
384364
365+
### Language stats algorithm
366+
367+
We use the following algorithm to calculate the languages percentages on the language card:
368+
369+
```js
370+
ranking_index = (byte_count ^ p) * (repo_count ^ q)
371+
```
372+
By default, only the byte count is used for determining the languages percentages shown on the language card (i.e. `p=1` and `q=0`). You can, however, use the `&p=` and `&q=` options to weight the language usage calculation. The values must be positive real numbers. More details about the algorithm can be found [here](Details here.](https://github.com/anuraghazra/github-readme-stats/issues/1600#issuecomment-1046056305)).
373+
374+
- `&p=1&q=0` - _(default)_ Orders by byte count.
375+
- `&p=0.5&q=0.5` - _(recommended)_ Uses both byte and repo count for ranking
376+
- `&p=0&q=1` - Orders by repo count
377+
378+
```md
379+
[![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&p=0.5&q=0.5)](https://github.com/anuraghazra/github-readme-stats)
380+
```
381+
385382
### Usage
386383

387384
Copy-paste this code into your readme and change the links.
@@ -440,7 +437,7 @@ You can use the `&hide_progress=true` option to hide the percentages and the pro
440437

441438
[![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&layout=compact)](https://github.com/anuraghazra/github-readme-stats)
442439

443-
- Hidden progress bars
440+
- Hidden progress bars
444441

445442
[![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&hide_progress=true)](https://github.com/anuraghazra/github-readme-stats)
446443

@@ -581,14 +578,14 @@ Since the GitHub API only allows 5k requests per hour, my `https://github-readme
581578
<details>
582579
<summary><b>:hammer_and_wrench: Step-by-step guide for deploying on other platforms</b></summary>
583580

584-
1. Fork or clone this repo as per your needs
585-
2. Add `express` to the dependencies section of `package.json`
586-
https://github.com/anuraghazra/github-readme-stats/blob/ba7c2f8b55eac8452e479c8bd38b044d204d0424/package.json#L54-L61
587-
3. Run `npm i` if needed (initial setup)
588-
4. Run `node express.js` to start the server, or set the entry point to `express.js` in `package.json` if you're deploying on a managed service
589-
https://github.com/anuraghazra/github-readme-stats/blob/ba7c2f8b55eac8452e479c8bd38b044d204d0424/package.json#L11
590-
5. You're done 🎉
591-
</details>
581+
1. Fork or clone this repo as per your needs
582+
2. Add `express` to the dependencies section of `package.json`
583+
<https://github.com/anuraghazra/github-readme-stats/blob/ba7c2f8b55eac8452e479c8bd38b044d204d0424/package.json#L54-L61>
584+
3. Run `npm i` if needed (initial setup)
585+
4. Run `node express.js` to start the server, or set the entry point to `express.js` in `package.json` if you're deploying on a managed service
586+
<https://github.com/anuraghazra/github-readme-stats/blob/ba7c2f8b55eac8452e479c8bd38b044d204d0424/package.json#L11>
587+
5. You're done 🎉
588+
</details>
592589

593590
### Keep your fork up to date
594591

src/fetchers/top-languages-fetcher.js

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -116,11 +116,10 @@ const fetchTopLanguages = async (username, exclude_repo = [], p = 1, q = 0) => {
116116
// add the size to the language size and increase repoCount.
117117
if (acc[prev.node.name] && prev.node.name === acc[prev.node.name].name) {
118118
langSize = prev.size + acc[prev.node.name].size;
119-
repoCount = repoCount + 1;
120-
}
121-
else {
119+
repoCount += 1;
120+
} else {
122121
// reset repoCount to 1
123-
// language must exist in atleast one repo to be detected
122+
// language must exist in at least one repo to be detected
124123
repoCount = 1;
125124
}
126125
return {
@@ -134,12 +133,11 @@ const fetchTopLanguages = async (username, exclude_repo = [], p = 1, q = 0) => {
134133
};
135134
}, {});
136135

137-
138-
Object.keys(repoNodes)
139-
.forEach((name) => {
140-
// comparison index calculation
141-
repoNodes[name].size = Math.pow(repoNodes[name].size, p) * Math.pow(repoNodes[name].count, q);
142-
})
136+
Object.keys(repoNodes).forEach((name) => {
137+
// comparison index calculation
138+
repoNodes[name].size =
139+
Math.pow(repoNodes[name].size, p) * Math.pow(repoNodes[name].count, q);
140+
});
143141

144142
const topLangs = Object.keys(repoNodes)
145143
.sort((a, b) => repoNodes[b].size - repoNodes[a].size)

tests/fetchTopLanguages.test.js

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -63,19 +63,19 @@ describe("FetchTopLanguages", () => {
6363
it("should fetch correct language data while using the new calculation", async () => {
6464
mock.onPost("https://api.github.com/graphql").reply(200, data_langs);
6565

66-
let repo = await fetchTopLanguages("anuraghazra", p = 0.5, q = 0.5);
66+
let repo = await fetchTopLanguages("anuraghazra", [], 0.5, 0.5);
6767
expect(repo).toStrictEqual({
6868
HTML: {
6969
color: "#0f0",
7070
count: 2,
7171
name: "HTML",
72-
size: 20,
72+
size: 20.000000000000004,
7373
},
7474
javascript: {
7575
color: "#0ff",
7676
count: 2,
7777
name: "javascript",
78-
size: 20,
78+
size: 20.000000000000004,
7979
},
8080
});
8181
});
@@ -103,7 +103,7 @@ describe("FetchTopLanguages", () => {
103103
it("should fetch correct language data while using the old calculation", async () => {
104104
mock.onPost("https://api.github.com/graphql").reply(200, data_langs);
105105

106-
let repo = await fetchTopLanguages("anuraghazra", p = 1, q = 0);
106+
let repo = await fetchTopLanguages("anuraghazra", [], 1, 0);
107107
expect(repo).toStrictEqual({
108108
HTML: {
109109
color: "#0f0",
@@ -123,7 +123,7 @@ describe("FetchTopLanguages", () => {
123123
it("should rank languages by the number of repositories they appear in", async () => {
124124
mock.onPost("https://api.github.com/graphql").reply(200, data_langs);
125125

126-
let repo = await fetchTopLanguages("anuraghazra", exclude_repo = [], p = 0, q = 1);
126+
let repo = await fetchTopLanguages("anuraghazra", [], 0, 1);
127127
expect(repo).toStrictEqual({
128128
HTML: {
129129
color: "#0f0",

0 commit comments

Comments
 (0)