Skip to content

Commit 8a7961f

Browse files
maguoweimaguowei
committed
docs: rewrite README and add Chinese version
1 parent 3a2aa87 commit 8a7961f

File tree

2 files changed

+180
-68
lines changed

2 files changed

+180
-68
lines changed

‎README.md‎

Lines changed: 70 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,110 @@
11
# Starred
22

3-
[![ci](https://github.com/maguowei/starred/actions/workflows/ci.yml/badge.svg)](https://github.com/maguowei/starred/actions/workflows/ci.yml)
3+
[![CI](https://github.com/maguowei/starred/actions/workflows/ci.yml/badge.svg)](https://github.com/maguowei/starred/actions/workflows/ci.yml)
44
[![Publish Python Package](https://github.com/maguowei/starred/actions/workflows/publish.yml/badge.svg)](https://github.com/maguowei/starred/actions/workflows/publish.yml)
55

6-
## Install
6+
English | [简体中文](README.zh-CN.md)
77

8-
```bash
8+
Create and maintain your own Awesome-style list from GitHub stars.
99

10-
$ pip install starred
11-
$ starred --username maguowei --token=xxxxxxxx --sort > README.md
12-
```
10+
## Features
11+
12+
- Generate a Markdown list from your starred repositories.
13+
- Group results by language (default) or repository topics.
14+
- Optionally sort categories alphabetically.
15+
- Write the generated file directly to a target GitHub repository.
16+
- Include private repositories with `--private`.
17+
18+
## Installation
1319

14-
## Usage
20+
Requires Python `3.10+`.
1521

1622
```bash
17-
$ starred --help
23+
pip install starred
24+
```
1825

19-
Usage: starred [OPTIONS]
26+
## Quick Start
2027

21-
GitHub starred
28+
1. Create a GitHub token: [Personal access tokens](https://github.com/settings/tokens)
29+
2. Generate a README from your stars:
2230

23-
creating your own Awesome List by GitHub stars!
31+
```bash
32+
export GITHUB_TOKEN=<your-token>
33+
starred --username <your-github-username> --sort > README.md
34+
```
2435

25-
example: starred --username maguowei --token=xxxxxxxx --sort > README.md
36+
## CLI Usage
2637

27-
Options:
28-
--username TEXT GitHub username [required]
29-
--token TEXT GitHub token [required]
30-
--sort sort by category[language/topic] name alphabetically
31-
[default: False]
38+
```bash
39+
starred --help
40+
```
3241

33-
--topic category by topic, default is category by language
34-
[default: False]
42+
Common options:
3543

36-
--topic_limit INTEGER topic stargazer_count gt number, set bigger to reduce
37-
topics number [default: 500]
44+
- `--username`: GitHub username (required)
45+
- `--token`: GitHub token (required)
46+
- `--sort`: Sort categories alphabetically
47+
- `--topic`: Group by topic instead of language
48+
- `--topic_limit`: Topic popularity threshold (default: `500`)
49+
- `--repository`: Target repository name to update/create
50+
- `--filename`: Target file name in the repository (default: `README.md`)
51+
- `--message`: Commit message used when updating a file
52+
- `--private`: Include private repositories
3853

39-
--repository TEXT repository name [default: ]
40-
--filename TEXT file name [default: README.md]
41-
--message TEXT commit message [default: update stars]
42-
--private include private repos [default: False]
43-
--version Show the version and exit.
44-
--help Show this message and exit.
45-
```
54+
## Update a Repository Directly
4655

47-
## Demo
56+
This command creates the repository if it does not exist, then updates `README.md` in that repository.
4857

4958
```bash
50-
# automatically create the repository
51-
$ export GITHUB_TOKEN=yourtoken
52-
$ starred --username yourname --repository awesome-stars --sort
59+
export GITHUB_TOKEN=<your-token>
60+
starred --username <your-github-username> --repository awesome-stars --sort
5361
```
5462

55-
- [`maguowei/awesome-stars`](https://github.com/maguowei/awesome-stars)
56-
- [update awesome-stars every day by GitHub Action](https://github.com/maguowei/awesome-stars/blob/master/.github/workflows/schedules.yml) the example with GitHub Action
57-
58-
### Who uses starred?
59-
60-
- by search: https://github.com/search?p=1&q=%22Generated+by+starred%22&type=Code
61-
- by topics:
62-
- https://github.com/topics/starred
63-
- https://github.com/topics/awesome-stars
63+
Example repository:
6464

65-
## Use [awesome-stars](https://github.com/maguowei/awesome-stars) as template
65+
- [maguowei/awesome-stars](https://github.com/maguowei/awesome-stars)
6666

67-
The simple way to create an awesome-stars repository is to use [maguowei/awesome-stars](https://github.com/maguowei/awesome-stars/generate) as template.
68-
It will auto update your awesome-stars repository every day by GitHub Action.
67+
## Use `awesome-stars` as a Template
6968

70-
1. Click [Create a new repository from awesome-stars](https://github.com/maguowei/awesome-stars/generate)
69+
The easiest setup is using [maguowei/awesome-stars](https://github.com/maguowei/awesome-stars/generate) as your template repository. It includes a scheduled GitHub Actions workflow for automatic updates.
7170

72-
![use-awesome-stars-as-template](https://raw.githubusercontent.com/maguowei/starred/master/imgs/use-awesome-stars-as-template.png)
71+
1. Click [Create a new repository from awesome-stars](https://github.com/maguowei/awesome-stars/generate).
7372

74-
2. [Setting the permissions of the GITHUB_TOKEN for your repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository)
73+
![Use awesome-stars as template](imgs/use-awesome-stars-as-template.png)
7574

76-
set permissions to `Read and write permissions` and click `Save` button
75+
2. Configure workflow token permissions:
76+
[Set `GITHUB_TOKEN` permissions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository)
7777

78-
![workflow-permissions](https://raw.githubusercontent.com/maguowei/starred/master/imgs/workflow-permissions.png)
78+
Set permissions to `Read and write permissions`, then click `Save`.
7979

80-
3. Run the workflow first time
80+
![Workflow permissions](imgs/workflow-permissions.png)
8181

82-
click `Run workflow` button
82+
3. Run the workflow once manually by clicking `Run workflow`.
8383

84-
![run-workflow](https://raw.githubusercontent.com/maguowei/starred/master/imgs/run-workflow.png)
84+
![Run workflow](imgs/run-workflow.png)
8585

86-
4. Customize the workflow schedule
86+
4. Customize the schedule in:
87+
[.github/workflows/schedules.yml#L5](https://github.com/maguowei/awesome-stars/blob/master/.github/workflows/schedules.yml#L5)
8788

88-
- [.github/workflows/schedules.yml#L5](https://github.com/maguowei/awesome-stars/blob/master/.github/workflows/schedules.yml#L5)
89+
![Schedule](imgs/schedule.png)
8990

90-
![schedule](https://raw.githubusercontent.com/maguowei/starred/master/imgs/schedule.png)
91+
## Who Uses `starred`?
9192

92-
## FAQ
93+
- Code search: [Generated by starred](https://github.com/search?p=1&q=%22Generated+by+starred%22&type=Code)
94+
- Topic pages:
95+
- [starred](https://github.com/topics/starred)
96+
- [awesome-stars](https://github.com/topics/awesome-stars)
9397

94-
1. Generate new token
98+
## Development
9599

96-
link: [Github Personal access tokens](https://github.com/settings/tokens)
100+
```bash
101+
uv sync --dev
102+
uv run starred --help
103+
```
97104

98-
2. Install the master branch version
105+
Install from source tarball:
99106

100-
```bash
101-
$ uv build
102-
$ pip install dist/starred-${x.x.x}.tar.gz
103-
```
104-
3. Dev & Run
105-
```bash
106-
uv sync --dev
107-
uv run starred --help
108-
```
107+
```bash
108+
uv build
109+
pip install dist/starred-<version>.tar.gz
110+
```

‎README.zh-CN.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Starred
2+
3+
[![CI](https://github.com/maguowei/starred/actions/workflows/ci.yml/badge.svg)](https://github.com/maguowei/starred/actions/workflows/ci.yml)
4+
[![Publish Python Package](https://github.com/maguowei/starred/actions/workflows/publish.yml/badge.svg)](https://github.com/maguowei/starred/actions/workflows/publish.yml)
5+
6+
[English](README.md) | 简体中文
7+
8+
基于你的 GitHub Stars 自动生成并维护 Awesome 风格的 Markdown 列表。
9+
10+
## 功能
11+
12+
- 从已 Star 的仓库生成 Markdown 列表。
13+
- 按语言（默认）或按仓库 Topic 分组。
14+
- 可按分类名称字母序排序。
15+
- 可直接写入并更新指定 GitHub 仓库中的文件。
16+
- 使用 `--private` 可包含私有仓库。
17+
18+
## 安装
19+
20+
要求 Python `3.10+`。
21+
22+
```bash
23+
pip install starred
24+
```
25+
26+
## 快速开始
27+
28+
1. 创建 GitHub Token：[Personal access tokens](https://github.com/settings/tokens)
29+
2. 基于你的 Stars 生成 README：
30+
31+
```bash
32+
export GITHUB_TOKEN=<your-token>
33+
starred --username <your-github-username> --sort > README.md
34+
```
35+
36+
## 命令行用法
37+
38+
```bash
39+
starred --help
40+
```
41+
42+
常用参数：
43+
44+
- `--username`：GitHub 用户名（必填）
45+
- `--token`：GitHub Token（必填）
46+
- `--sort`：按分类名称字母序排序
47+
- `--topic`：按 Topic 分组（默认按语言）
48+
- `--topic_limit`：Topic 热度阈值（默认 `500`）
49+
- `--repository`：要更新/创建的目标仓库名
50+
- `--filename`：仓库内目标文件名（默认 `README.md`）
51+
- `--message`：更新文件时使用的 commit message
52+
- `--private`：包含私有仓库
53+
54+
## 直接更新目标仓库
55+
56+
下面的命令会在仓库不存在时自动创建仓库，然后更新该仓库中的 `README.md`。
57+
58+
```bash
59+
export GITHUB_TOKEN=<your-token>
60+
starred --username <your-github-username> --repository awesome-stars --sort
61+
```
62+
63+
示例仓库：
64+
65+
- [maguowei/awesome-stars](https://github.com/maguowei/awesome-stars)
66+
67+
## 使用 `awesome-stars` 模板
68+
69+
推荐直接使用 [maguowei/awesome-stars](https://github.com/maguowei/awesome-stars/generate) 模板仓库。它内置了 GitHub Actions 定时任务，可自动更新。
70+
71+
1. 点击 [Create a new repository from awesome-stars](https://github.com/maguowei/awesome-stars/generate)。
72+
73+
![Use awesome-stars as template](imgs/use-awesome-stars-as-template.png)
74+
75+
2. 配置工作流 Token 权限：
76+
[Set `GITHUB_TOKEN` permissions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository)
77+
78+
将权限设置为 `Read and write permissions`，然后点击 `Save`。
79+
80+
![Workflow permissions](imgs/workflow-permissions.png)
81+
82+
3. 首次手动运行工作流，点击 `Run workflow`。
83+
84+
![Run workflow](imgs/run-workflow.png)
85+
86+
4. 按需修改定时配置：
87+
[.github/workflows/schedules.yml#L5](https://github.com/maguowei/awesome-stars/blob/master/.github/workflows/schedules.yml#L5)
88+
89+
![Schedule](imgs/schedule.png)
90+
91+
## 谁在使用 `starred`？
92+
93+
- 代码搜索：[Generated by starred](https://github.com/search?p=1&q=%22Generated+by+starred%22&type=Code)
94+
- Topic 页面：
95+
- [starred](https://github.com/topics/starred)
96+
- [awesome-stars](https://github.com/topics/awesome-stars)
97+
98+
## 开发
99+
100+
```bash
101+
uv sync --dev
102+
uv run starred --help
103+
```
104+
105+
从源码构建并安装：
106+
107+
```bash
108+
uv build
109+
pip install dist/starred-<version>.tar.gz
110+
```

0 commit comments

Comments
 (0)
⚡