Skip to content

Commit 1d323a3

Browse files
calchiwocalchiwo
authored
Merge pull request #225 from calchiwo/docs/restructure-installation-and-platform-guides
Restructure documentation into dedicated installation and platform guides
2 parents 29465cc + 0b7d926 commit 1d323a3

3 files changed

Lines changed: 220 additions & 152 deletions

File tree

‎README.md‎

Lines changed: 31 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -31,152 +31,57 @@ ExplainThisRepo analyzes real project signals; configs, entrypoints, manifests,
3131

3232
## Installation
3333

34-
### Option 1: install with pip (Python source version):
34+
ExplainThisRepo supports multiple installation methods:
3535

36-
Requirements: Python 3.9+
36+
- pip (Python package)
37+
- npm (prebuilt native binaries)
38+
- .NET global tool
39+
- standalone binaries
40+
41+
### Quick install
42+
43+
#### pip
3744

3845
```bash
3946
pip install explainthisrepo
40-
explainthisrepo owner/repo
41-
42-
# explainthisrepo .
43-
# explainthisrepo ./path/to/directory
44-
# explainthisrepo ./path/to/file.py
45-
# explainthisrepo owner/repo/path/to/file.py
46-
# explainthisrepo owner/repo/path/to/directory
4747
```
4848

4949
Alternatively,
5050

5151
```bash
5252
pipx install explainthisrepo
53-
explainthisrepo owner/repo
54-
```
55-
56-
After installation, use any of the available commands:
57-
58-
```bash
59-
explainthisrepo owner/repo
60-
explain-this-repo owner/repo
61-
etr owner/repo
6253
```
6354

64-
To install support for specific models:
65-
66-
```bash
67-
pip install explainthisrepo[gemini]
68-
pip install explainthisrepo[openai]
69-
pip install explainthisrepo[anthropic]
70-
pip install explainthisrepo[groq]
71-
```
72-
73-
Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`, `torvalds/linux`).
74-
75-
### Option 2: Install with npm (prebuilt binary, no Python install required)
76-
77-
Install globally and use forever:
55+
#### npm
7856

7957
```bash
8058
npm install -g explainthisrepo
81-
explainthisrepo owner/repo
8259
```
8360

84-
<details>
85-
<pre>
86-
<code>
87-
explainthisrepo .
88-
explainthisrepo ./path/to/directory
89-
explainthisrepo ./path/to/file.py
90-
explainthisrepo owner/repo/path/to/file.py
91-
explainthisrepo owner/repo/path/to/directory
92-
</code>
93-
</pre>
94-
</details>
95-
96-
Or without install:
61+
#### .NET
9762

9863
```bash
99-
npx explainthisrepo owner/repo
64+
dotnet tool install -g ExplainThisRepo
10065
```
10166

102-
<details>
103-
<pre>
104-
<code>
105-
npx explainthisrepo .
106-
npx explainthisrepo ./path/to/directory
107-
npx explainthisrepo ./path/to/file.py
108-
npx explainthisrepo owner/repo/path/to/file.py
109-
npx explainthisrepo owner/repo/path/to/directory
110-
</code>
111-
</pre>
112-
</details>
113-
114-
### Option 3: Install with .NET (C# Global Tool)
115-
116-
Requirements: .NET 8, 9, or 10:
67+
#### Run
11768

11869
```bash
119-
dotnet tool install -g explainthisrepo
12070
explainthisrepo owner/repo
121-
122-
# dotnet tool install -g explainthisrepo
123-
# explainthisrepo .
12471
```
12572

126-
## How it works
127-
128-
ExplainThisRepo has one core engine and multiple distribution layers.
129-
130-
- Python is the source of truth for analysis, prompts, providers, and output
131-
- npm ships the Node launcher plus prebuilt native binaries
132-
- .NET ships the same native binary as a global tool and publishes to NuGet
133-
- GitHub Releases publish the standalone binaries
134-
135-
The Node and .NET layers are launchers only. They detect the current platform, locate the matching bundled binary, and execute it with the user’s arguments.
136-
137-
The same native binary is what actually performs the work.
138-
139-
## Distribution model
140-
141-
ExplainThisRepo is shipped in multiple ways:
142-
143-
- `pip` for Python users
144-
- `npm` for Node users
145-
- `dotnet tool` for .NET users
146-
- standalone binaries for direct download
147-
148-
All of them run the same core Python engine compiled into native binaries.
149-
150-
### Option 4: Download standalone binary
151-
152-
Prebuilt standalone binaries are available for macOS, Linux, and Windows.
153-
154-
> Standalone binaries require no Python or Node installation and run as a single executable.
155-
156-
Download the latest release: [ExplainThisRepo latest releases](https://github.com/calchiwo/ExplainThisRepo/releases/latest)
157-
158-
Or install directly:
159-
<details>
160-
macOS
73+
After installation, use any of the available commands:
16174

16275
```bash
163-
curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-darwin-arm64 -o explainthisrepo
164-
chmod +x explainthisrepo
76+
explainthisrepo owner/repo
77+
explain-this-repo owner/repo
78+
etr owner/repo
16579
```
16680

167-
Linux
168-
169-
```bash
170-
curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-linux-x64 -o explainthisrepo
171-
chmod +x explainthisrepo
172-
```
81+
Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`, `torvalds/linux`).
17382

174-
Windows (PowerShell)
17583

176-
```powershell
177-
curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-win-x64.exe -o explainthisrepo.exe
178-
```
179-
</details>
84+
For full installation instructions, platform-specific notes, standalone binaries, Termux support, and advanced setup: [docs/INSTALLATION.md](https://github.com/calchiwo/ExplainThisRepo/blob/main/docs/INSTALLATION.md)
18085

18186
## Configuration
18287

@@ -198,6 +103,15 @@ explainthisrepo init
198103

199104
> For details about how initialization works, see [docs/INIT.md](https://github.com/calchiwo/ExplainThisRepo/blob/main/docs/INIT.md).
200105
106+
To install support for specific models:
107+
108+
```bash
109+
pip install explainthisrepo[gemini]
110+
pip install explainthisrepo[openai]
111+
pip install explainthisrepo[anthropic]
112+
pip install explainthisrepo[groq]
113+
```
114+
201115
## GitHub token Access (Private Repos & Rate Limits)
202116

203117
ExplainThisRepo supports GitHub authentication for:
@@ -534,46 +448,11 @@ Use the `--doctor` flag to verify the environment, network connectivity, and API
534448
explainthisrepo --doctor
535449
```
536450

537-
## Termux (Android) install notes
538-
539-
Termux has some environment limitations that can make `pip install explainthisrepo` fail to create the `explainthisrepo` command in `$PREFIX/bin`.
540-
541-
However, it's recommended you install using:
542-
543-
```bash
544-
pip install --user -U explainthisrepo
545-
```
546-
547-
Make sure your user bin directory is on your PATH:
548-
549-
```bash
550-
export PATH="$HOME/.local/bin:$PATH"
551-
```
552-
553-
> Tip: Add the PATH export to your `~/.bashrc` or `~/.zshrc` so it persists.
554-
555-
### Alternative (No PATH changes)
451+
## Termux (Android)
556452

557-
If you do not want to modify PATH, you can run ExplainThisRepo as a module:
453+
ExplainThisRepo supports Termux on Android.
558454

559-
```bash
560-
python -m explain_this_repo owner/repo
561-
```
562-
563-
### Gemini support on Termux
564-
565-
Installing Gemini support may require building Rust-based dependencies on Android, which can take time on first install:
566-
567-
```bash
568-
pip install --user -U "explainthisrepo[gemini]"
569-
```
570-
571-
For mobile environments like Termux where compiling Python dependencies can be slow,
572-
you can also run ExplainThisRepo using the Node.js version:
573-
574-
```bash
575-
npx explainthisrepo owner/repo
576-
```
455+
For installation notes, PATH setup, Gemini support, and mobile-specific recommendations: see [docs/TERMUX.md](https://github.com/calchiwo/ExplainThisRepo/blob/main/docs/TERMUX.md)
577456

578457
## Philosophy
579458

‎docs/INSTALLATION.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Installation
2+
3+
### Option 1: install with pip (Python source version):
4+
5+
Requirements: Python 3.9+
6+
7+
```bash
8+
pip install explainthisrepo
9+
explainthisrepo owner/repo
10+
11+
# explainthisrepo .
12+
# explainthisrepo ./path/to/directory
13+
# explainthisrepo ./path/to/file.py
14+
# explainthisrepo owner/repo/path/to/file.py
15+
# explainthisrepo owner/repo/path/to/directory
16+
```
17+
18+
Alternatively,
19+
20+
```bash
21+
pipx install explainthisrepo
22+
explainthisrepo owner/repo
23+
```
24+
25+
After installation, use any of the available commands:
26+
27+
```bash
28+
explainthisrepo owner/repo
29+
explain-this-repo owner/repo
30+
etr owner/repo
31+
```
32+
33+
To install support for specific models:
34+
35+
```bash
36+
pip install explainthisrepo[gemini]
37+
pip install explainthisrepo[openai]
38+
pip install explainthisrepo[anthropic]
39+
pip install explainthisrepo[groq]
40+
```
41+
42+
Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`, `torvalds/linux`).
43+
44+
### Option 2: Install with npm (prebuilt binary, no Python install required)
45+
46+
Install globally and use forever:
47+
48+
```bash
49+
npm install -g explainthisrepo
50+
explainthisrepo owner/repo
51+
```
52+
53+
<details>
54+
<pre>
55+
<code>
56+
explainthisrepo .
57+
explainthisrepo ./path/to/directory
58+
explainthisrepo ./path/to/file.py
59+
explainthisrepo owner/repo/path/to/file.py
60+
explainthisrepo owner/repo/path/to/directory
61+
</code>
62+
</pre>
63+
</details>
64+
65+
Or without install:
66+
67+
```bash
68+
npx explainthisrepo owner/repo
69+
```
70+
71+
<details>
72+
<pre>
73+
<code>
74+
npx explainthisrepo .
75+
npx explainthisrepo ./path/to/directory
76+
npx explainthisrepo ./path/to/file.py
77+
npx explainthisrepo owner/repo/path/to/file.py
78+
npx explainthisrepo owner/repo/path/to/directory
79+
</code>
80+
</pre>
81+
</details>
82+
83+
### Option 3: Install with .NET (C# Global Tool)
84+
85+
Requirements: .NET 8, 9, or 10:
86+
87+
```bash
88+
dotnet tool install -g ExplainThisRepo
89+
explainthisrepo owner/repo
90+
91+
# dotnet tool install -g ExplainThisRepo
92+
# explainthisrepo .
93+
```
94+
95+
## How it works
96+
97+
ExplainThisRepo has one core engine and multiple distribution layers.
98+
99+
- Python is the source of truth for analysis, prompts, providers, and output
100+
- npm ships the Node launcher plus prebuilt native binaries
101+
- .NET ships the same native binary as a global tool and publishes to NuGet
102+
- GitHub Releases publish the standalone binaries
103+
104+
The Node and .NET layers are launchers only. They detect the current platform, locate the matching bundled binary, and execute it with the user’s arguments.
105+
106+
The same native binary is what actually performs the work.
107+
108+
## Distribution model
109+
110+
ExplainThisRepo can be installed in multiple ways:
111+
112+
- `pip` for Python users
113+
- `npm` for Node users
114+
- `dotnet tool` for .NET users
115+
- standalone binaries for direct download
116+
117+
All of them run the same core Python engine compiled into native binaries.
118+
119+
### Option 4: Download standalone binary
120+
121+
Prebuilt standalone binaries are available for macOS, Linux, and Windows.
122+
123+
> Standalone binaries require no Python or Node installation and run as a single executable.
124+
125+
Download the latest release: [ExplainThisRepo latest releases](https://github.com/calchiwo/ExplainThisRepo/releases/latest)
126+
127+
Or install directly:
128+
129+
macOS
130+
131+
```bash
132+
curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-darwin-arm64 -o explainthisrepo
133+
chmod +x explainthisrepo
134+
```
135+
136+
Linux
137+
138+
```bash
139+
curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-linux-x64 -o explainthisrepo
140+
chmod +x explainthisrepo
141+
```
142+
143+
Windows (PowerShell)
144+
145+
```powershell
146+
curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-win-x64.exe -o explainthisrepo.exe
147+
```

0 commit comments

Comments
 (0)