Skip to content

Commit 0448031

Browse files
zhravanzhravan
authored
docs: improved docs (zhravan#106)
1 parent 8051828 commit 0448031

5 files changed

Lines changed: 146 additions & 71 deletions

File tree

‎docs/README.md‎

Lines changed: 0 additions & 44 deletions
This file was deleted.

‎docs/about.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@ title: About
2626
<div class="gopher-card">
2727
<h2>Features</h2>
2828
<ul>
29-
<li>37 concept exercises covering Go fundamentals</li>
30-
<li>9 project exercises for real applications</li>
29+
<li>Concept exercises covering Go fundamentals</li>
30+
<li>Project exercises for real applications</li>
3131
<li>Progressive difficulty levels</li>
3232
<li>Instant feedback and verification</li>
3333
<li>Hints and solutions when needed</li>

‎docs/contributing.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,9 @@ title: Contributing
3434
<h2>Creating Exercises</h2>
3535
<p>Each exercise needs:</p>
3636
<ul>
37-
<li>Template file (incomplete code for students)</li>
37+
<li>Template file (incomplete code for learners to complete)</li>
3838
<li>Test file (verification tests)</li>
39-
<li>Solution file (complete implementation)</li>
39+
<li>Solution file (complete implementation, base code is already in place which will run the test cases written for template to picked for solutions as well)</li>
4040
<li>Catalog entry in <code>catalog.yaml</code></li>
4141
</ul>
4242
</div>
@@ -53,13 +53,14 @@ title: Contributing
5353

5454
<div class="gopher-card">
5555
<h2>Testing</h2>
56-
<p>Before submitting your changes:</p>
57-
<pre><code># Run all tests
58-
go test ./...
56+
<p>Before submitting your changes, build locally and verify exercises using the CLI:</p>
57+
<pre><code># Build the CLI
58+
go build -o bin/golearn ./cmd/golearn
59+
chmod +x bin/golearn
5960

60-
# Test exercises
61+
# Verify template exercises (incomplete templates should fail)
6162
./bin/golearn verify
6263

63-
# Test with solutions
64+
# Verify a specific exercise with its solution (should pass)
6465
./bin/golearn verify 01_hello --solution</code></pre>
6566
</div>

‎docs/getting-started.md‎

Lines changed: 133 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -22,30 +22,150 @@ title: Getting Started
2222

2323
<div class="gopher-card">
2424
<h2>Installation</h2>
25-
<pre><code>git clone https://github.com/your-username/golearn.git
26-
cd golearn
27-
go build -o bin/golearn ./cmd/golearn
28-
chmod +x bin/golearn</code></pre>
25+
<pre><code>go install github.com/zhravan/golearn/cmd/golearn@latest
26+
golearn --help</code></pre>
2927
</div>
3028

3129
<div class="gopher-card">
3230
<h2>First Exercise</h2>
3331
<ol>
34-
<li>List exercises: <code>./bin/golearn list</code></li>
35-
<li>Start first exercise: <code>./bin/golearn verify 01_hello</code></li>
36-
<li>Get hints: <code>./bin/golearn hint 01_hello</code></li>
32+
<li>List exercises: <code>golearn list</code></li>
33+
<li>Start first exercise: <code>golearn verify 01_hello</code></li>
34+
<li>Get hints: <code>golearn hint 01_hello</code></li>
3735
<li>Edit the template file and implement the solution</li>
38-
<li>Verify your solution: <code>./bin/golearn verify 01_hello</code></li>
36+
<li>Verify your solution: <code>golearn verify 01_hello</code></li>
37+
</ol>
38+
</div>
39+
40+
<div class="gopher-card">
41+
<h2>Getting Started as a Learner (CLI only)</h2>
42+
<ol>
43+
<li>List available exercises: <code>golearn list</code></li>
44+
<li>Initialize local templates (optional): <code>golearn init</code></li>
45+
<li>Try an exercise (expect failure until you implement it): <code>golearn verify 01_hello</code></li>
46+
<li>Read a hint: <code>golearn hint 01_hello</code></li>
47+
<li>Edit the template file for the exercise, then re-run <code>verify</code></li>
48+
<li>See your overall progress: <code>golearn progress</code></li>
49+
<li>Optionally view the reference solution: <code>golearn solution 01_hello</code></li>
50+
<li>Reset an exercise to its starter state: <code>golearn reset 01_hello</code></li>
51+
</ol>
52+
</div>
53+
54+
<div class="gopher-card">
55+
<h2>Getting Started as a Contributor</h2>
56+
<ol>
57+
<li>Read the contribution guide: <a href="{{ '/contributing' | relative_url }}">Contributing</a></li>
58+
<li>Fork and clone the repo, create a feature branch</li>
59+
<li>Build the CLI locally: <code>go build -o bin/golearn ./cmd/golearn && chmod +x bin/golearn</code></li>
60+
<li>Develop your exercise/update under <code>internal/exercises</code></li>
61+
<li>Verify templates (incomplete templates should fail): <code>./bin/golearn verify</code></li>
62+
<li>Verify specific exercise with solution (should pass): <code>./bin/golearn verify 01_hello --solution</code></li>
63+
<li>Run auxiliary checks locally: <code>go fmt ./...</code> and <code>go vet ./...</code></li>
64+
<li>Open a Pull Request</li>
3965
</ol>
4066
</div>
4167

4268
<div class="gopher-card">
4369
<h2>Commands</h2>
4470
<ul>
45-
<li><code>./bin/golearn list</code> - List all exercises</li>
46-
<li><code>./bin/golearn verify [exercise]</code> - Verify an exercise</li>
47-
<li><code>./bin/golearn hint [exercise]</code> - Get hints</li>
48-
<li><code>./bin/golearn progress</code> - Show progress</li>
49-
<li><code>./bin/golearn solution [exercise]</code> - View solution</li>
71+
<li><code>golearn list</code> - List all exercises</li>
72+
<li><code>golearn verify [exercise]</code> - Verify an exercise</li>
73+
<li><code>golearn hint [exercise]</code> - Get hints</li>
74+
<li><code>golearn progress</code> - Show progress</li>
75+
<li><code>golearn solution [exercise]</code> - View solution</li>
5076
</ul>
77+
78+
<h3>CLI Commands</h3>
79+
<table>
80+
<thead>
81+
<tr>
82+
<th>Command</th>
83+
<th>Description</th>
84+
<th>Example</th>
85+
</tr>
86+
</thead>
87+
<tbody>
88+
<tr>
89+
<td><code>golearn --help</code></td>
90+
<td>Show help and available commands</td>
91+
<td><code>./bin/golearn --help</code></td>
92+
</tr>
93+
<tr>
94+
<td><code>golearn list</code></td>
95+
<td>List all available exercises</td>
96+
<td><code>./bin/golearn list</code></td>
97+
</tr>
98+
<tr>
99+
<td><code>./bin/golearn verify [exercise]</code></td>
100+
<td>Verify all templates or a specific exercise</td>
101+
<td>
102+
<div><code>golearn verify</code></div>
103+
<div><code>golearn verify 01_hello</code></div>
104+
</td>
105+
</tr>
106+
<tr>
107+
<td><code>./bin/golearn verify [exercise] --solution</code></td>
108+
<td>Verify using the reference solution (should pass)</td>
109+
<td><code>golearn verify 01_hello --solution</code></td>
110+
</tr>
111+
<tr>
112+
<td><code>./bin/golearn hint [exercise]</code></td>
113+
<td>Show hints for a specific exercise</td>
114+
<td><code>golearn hint 01_hello</code></td>
115+
</tr>
116+
<tr>
117+
<td><code>./bin/golearn solution [exercise]</code></td>
118+
<td>View the reference solution (may prompt for confirmation)</td>
119+
<td><code>golearn solution 01_hello</code></td>
120+
</tr>
121+
<tr>
122+
<td><code>golearn progress</code></td>
123+
<td>Display your overall progress</td>
124+
<td><code>./bin/golearn progress</code></td>
125+
</tr>
126+
<tr>
127+
<td><code>./bin/golearn reset [exercise]</code></td>
128+
<td>Reset an exercise to its starter template</td>
129+
<td><code>golearn reset 01_hello</code></td>
130+
</tr>
131+
<tr>
132+
<td><code>golearn init</code></td>
133+
<td>Initialize local exercise templates</td>
134+
<td><code>./bin/golearn init</code></td>
135+
</tr>
136+
<tr>
137+
<td><code>./bin/golearn publish [--dry-run]</code></td>
138+
<td>Run publish routine (use <code>--dry-run</code> to preview)</td>
139+
<td><code>golearn publish --dry-run</code></td>
140+
</tr>
141+
<tr>
142+
<td><code>golearn watch</code></td>
143+
<td>Watch files and re-verify on changes</td>
144+
<td><code>./bin/golearn watch</code></td>
145+
</tr>
146+
</tbody>
147+
</table>
148+
149+
<h3>Global Flags</h3>
150+
<table>
151+
<thead>
152+
<tr>
153+
<th>Flag</th>
154+
<th>Description</th>
155+
<th>Example</th>
156+
</tr>
157+
</thead>
158+
<tbody>
159+
<tr>
160+
<td><code>--no-color</code></td>
161+
<td>Disable colored output</td>
162+
<td><code>golearn --no-color list</code></td>
163+
</tr>
164+
<tr>
165+
<td><code>--theme=&lt;name&gt;</code></td>
166+
<td>Set output theme (<code>high-contrast</code>, <code>monochrome</code>)</td>
167+
<td><code>golearn --theme=high-contrast list</code></td>
168+
</tr>
169+
</tbody>
170+
</table>
51171
</div>

‎docs/index.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,10 @@ title: Home
2929
<h2>Quick Start</h2>
3030
<ol>
3131
<li>Install Go 1.22+</li>
32-
<li>Clone the repository</li>
32+
<li>Install the CLI</li>
3333
<li>Run your first exercise</li>
3434
</ol>
3535

36-
<pre><code>git clone https://github.com/your-username/golearn.git
37-
cd golearn
38-
go build -o bin/golearn ./cmd/golearn
39-
./bin/golearn verify 01_hello</code></pre>
36+
<pre><code>go install github.com/zhravan/golearn/cmd/golearn@latest
37+
golearn verify 01_hello</code></pre>
4038
</div>

0 commit comments

Comments
 (0)