Skip to content

Commit ac4ed0a

Browse files
abhiksarkabhiksark
committed
Merge branch 'feature/docs-site'
2 parents d96c984 + 4c7a724 commit ac4ed0a

14 files changed

Lines changed: 377 additions & 1 deletion

‎.github/workflows/pages.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
- uses: actions/setup-python@v5
23+
with:
24+
python-version: "3.13"
25+
cache: pip
26+
cache-dependency-path: requirements-docs.txt
27+
- uses: actions/configure-pages@v5
28+
- run: python -m pip install -r requirements-docs.txt
29+
- run: mkdocs build --strict
30+
- uses: actions/upload-pages-artifact@v3
31+
with:
32+
path: site
33+
34+
deploy:
35+
environment:
36+
name: github-pages
37+
url: ${{ steps.deployment.outputs.page_url }}
38+
runs-on: ubuntu-latest
39+
needs: build
40+
steps:
41+
- id: deployment
42+
uses: actions/deploy-pages@v4

‎Readme.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
[![Tests](https://img.shields.io/badge/tests-125%20passing-brightgreen)](#development)
77
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
88

9+
Documentation: [pylings.abhik.ai](https://pylings.abhik.ai/)
10+
911
Python learnings, Rustlings-style, in a live terminal TUI.
1012

1113
Pylings helps you learn Python by fixing small broken programs and watching

‎docs-site/CNAME‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pylings.abhik.ai

‎docs-site/contributing.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Contributing
2+
3+
Read `AGENTS.md` for repository conventions and `CONTRIBUTING.md` for the
4+
contributor workflow.
5+
6+
## Development Setup
7+
8+
```bash
9+
git clone git@github.com:abhiksark/pylings.git
10+
cd pylings
11+
pip install -e ".[dev]"
12+
python -m pytest -q
13+
```
14+
15+
## Test Commands
16+
17+
```bash
18+
python -m pytest -q
19+
pylings --root tests/fixtures/passing_curriculum verify
20+
python -m build
21+
```
22+
23+
Use unit tests for core behavior, integration tests for CLI and workspace flows,
24+
and TUI tests for Textual keyboard interactions.
25+
26+
## Curriculum Changes
27+
28+
Update these together:
29+
30+
```text
31+
exercises/<topic>/<exercise>.py
32+
checks/<topic>/<exercise>.py
33+
solutions/<exercise>.py
34+
info.toml
35+
```
36+
37+
Keep exercise names stable and mirrored. Use topic-plus-number names such as
38+
`variables1.py`, `collections10.py`, and `oop_advanced12.py`.

‎docs-site/curriculum.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Curriculum
2+
3+
Pylings ships 292 exercises across 31 topics. Each exercise has a learner file,
4+
a hidden check file, a hint, and a Python documentation link in `info.toml`.
5+
6+
## Topic Coverage
7+
8+
| Topic | Exercises |
9+
|---|---:|
10+
| `variables` | 10 |
11+
| `strings` | 10 |
12+
| `conditionals` | 10 |
13+
| `loops` | 10 |
14+
| `functions` | 10 |
15+
| `lists` | 10 |
16+
| `tuples` | 10 |
17+
| `dictionaries` | 10 |
18+
| `sets` | 10 |
19+
| `comprehensions` | 10 |
20+
| `exceptions` | 10 |
21+
| `file_io` | 10 |
22+
| `classes` | 12 |
23+
| `functional` | 10 |
24+
| `decorators` | 10 |
25+
| `generators` | 10 |
26+
| `context_managers` | 8 |
27+
| `dataclasses` | 8 |
28+
| `type_hints` | 8 |
29+
| `regex` | 10 |
30+
| `testing` | 12 |
31+
| `recursion` | 8 |
32+
| `modules` | 8 |
33+
| `collections` | 10 |
34+
| `itertools` | 8 |
35+
| `json` | 8 |
36+
| `datetime` | 8 |
37+
| `enums` | 6 |
38+
| `pathlib` | 6 |
39+
| `oop_advanced` | 12 |
40+
| `async` | 10 |
41+
42+
## File Model
43+
44+
```text
45+
exercises/<topic>/<exercise>.py # learner-editable code
46+
checks/<topic>/<exercise>.py # hidden assertions
47+
solutions/<exercise>.py # reference answer
48+
info.toml # order, hints, docs links
49+
```
50+
51+
Exercise and check filenames stay mirrored. For example,
52+
`exercises/lists/lists3.py` is checked by `checks/lists/lists3.py`.
53+
54+
## Progress
55+
56+
Progress is stored in the learner workspace, not in the package repository.
57+
Passing checks mark exercises complete. Reset restores a learner file from the
58+
original snapshot created during `pylings init`.

‎docs-site/index.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Pylings
2+
3+
Python learnings, Rustlings-style, in a live terminal TUI.
4+
5+
![Pylings terminal demo](https://raw.githubusercontent.com/abhiksark/pylings/main/docs/assets/demos/pylings-demo.gif)
6+
7+
Pylings helps learners practice Python by fixing small broken programs and
8+
watching checks rerun as they work. The project includes 292 exercises across
9+
31 topics, hidden pytest-style checks, a Textual editor, progressive hints, and
10+
bundled Python documentation snippets for offline-friendly practice.
11+
12+
## Start Here
13+
14+
```bash
15+
pipx install "git+https://github.com/abhiksark/pylings.git@v0.1.0"
16+
pylings init --path ~/pylings-workspace
17+
cd ~/pylings-workspace
18+
pylings
19+
```
20+
21+
The package name reserved for PyPI publishing is `python-learnings`. Until the
22+
PyPI release is live, install the stable v0.1.0 release from the GitHub tag.
23+
24+
## What You Get
25+
26+
- Rustlings-inspired Python coding practice in the terminal.
27+
- Live exercise verification while editing.
28+
- Topic picker, progress tracking, reset, hints, and one-shot CLI commands.
29+
- Local docs window with links back to the official Python documentation.
30+
- A self-contained learner workspace created by `pylings init`.
31+
32+
## Project Status
33+
34+
Pylings is currently `v0.1.0` alpha. The public API, CLI, and curriculum are
35+
usable, but the project is still hardening packaging, docs, first-run flow, and
36+
release automation.

‎docs-site/interface.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Interface
2+
3+
## Coding Screen
4+
5+
![Coding screen](https://raw.githubusercontent.com/abhiksark/pylings/main/docs/assets/screenshots/coding-screen.png)
6+
7+
The coding screen keeps the exercise, editor, output, progress, and exercise
8+
list in one terminal view. Checks rerun as files change.
9+
10+
## Topic Picker
11+
12+
![Topic picker](https://raw.githubusercontent.com/abhiksark/pylings/main/docs/assets/screenshots/topic-picker.png)
13+
14+
The topic picker shows curriculum progress by topic and lets learners jump back
15+
to a topic without leaving the terminal.
16+
17+
## Local Docs Window
18+
19+
![Local docs reference](https://raw.githubusercontent.com/abhiksark/pylings/main/docs/assets/screenshots/docs-reference.png)
20+
21+
The docs window opens bundled Python reference snippets for the current
22+
exercise. Press `O` from that window to open the official Python docs page.
23+
24+
## Key Bindings
25+
26+
| Key | Action |
27+
|---|---|
28+
| `F1` | Toggle hint |
29+
| `F2` | Reset the current exercise |
30+
| `F3` | Toggle the exercise list |
31+
| `F4` | Return to the topic picker |
32+
| `F5` | Show the local Python reference |
33+
| `O` | Open official docs from the reference window |
34+
| `Esc` | Close docs, or quit from main screens |
35+
| `Ctrl+Q` | Quit |

‎docs-site/local-docs.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Local Docs
2+
3+
Pylings bundles short Python reference snippets so learners can stay in the
4+
terminal while solving exercises.
5+
6+
## In The TUI
7+
8+
- Press `F5` to open the local docs window for the current exercise.
9+
- Press `O` from the docs window to open the official Python docs page.
10+
- Press `Esc` to close the docs window and return to the exercise.
11+
12+
## Source Material
13+
14+
Bundled snippets are generated from the official Python documentation. Licensing
15+
details live in `pylings/docs/NOTICE.md`.
16+
17+
## Refresh Snippets
18+
19+
Run this from the repository root:
20+
21+
```bash
22+
python scripts/fetch_python_docs.py
23+
```
24+
25+
The generated files live under:
26+
27+
```text
28+
pylings/docs/index.json
29+
pylings/docs/topics/
30+
```
31+
32+
When adding or changing exercises, keep `info.toml` docs links aligned with the
33+
local topic snippets.

‎docs-site/quick-start.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Quick Start
2+
3+
## Install
4+
5+
Install the current release from GitHub:
6+
7+
```bash
8+
pipx install "git+https://github.com/abhiksark/pylings.git@v0.1.0"
9+
```
10+
11+
After PyPI publishing is enabled, the package install path will be:
12+
13+
```bash
14+
pipx install python-learnings
15+
```
16+
17+
The command installed by the package is `pylings`.
18+
19+
## Create A Workspace
20+
21+
```bash
22+
pylings init --path ~/pylings-workspace
23+
cd ~/pylings-workspace
24+
pylings
25+
```
26+
27+
`pylings init` copies exercises, hidden checks, reference solutions, and reset
28+
snapshots into a learner workspace. Run `pylings` from that workspace to open
29+
the first pending exercise.
30+
31+
## Useful Commands
32+
33+
```bash
34+
pylings list
35+
pylings topics
36+
pylings hint variables1
37+
pylings run variables1
38+
pylings dry-run variables1
39+
pylings reset variables1 --yes
40+
pylings update
41+
```
42+
43+
Use `pylings list` to inspect progress, `pylings hint <exercise>` for help, and
44+
`pylings reset <exercise> --yes` to restore an exercise to its original broken
45+
state.
46+
47+
## Exercise Loop
48+
49+
Each exercise contains a `# I AM NOT DONE` marker. Fix the code, remove the
50+
marker, and let Pylings run the hidden check. Passing checks mark the exercise
51+
complete and move the progress state forward.

‎docs-site/roadmap.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Roadmap
2+
3+
Pylings is currently `v0.1.0` alpha. The core learner loop works, but the
4+
project still needs product hardening before calling it stable.
5+
6+
## Current Release
7+
8+
- 292 exercises across 31 topics.
9+
- Live Textual editor and automatic checks.
10+
- Topic picker, progress state, reset, hints, and CLI commands.
11+
- Bundled Python docs snippets with official docs links.
12+
- GitHub install path for `v0.1.0`.
13+
14+
## Next Work
15+
16+
- Finish PyPI publishing for the `python-learnings` project name.
17+
- Improve first-run onboarding and empty-state copy.
18+
- Harden keyboard flow around `Enter`, `Esc`, `F4`, and `F5`.
19+
- Add more TUI tests for the coding screen, docs window, and topic picker.
20+
- Add a release smoke test that installs the built wheel and exercises the CLI.
21+
- Continue auditing exercises for clearer hints and stronger hidden checks.
22+
23+
## Release Policy
24+
25+
Pylings follows Semantic Versioning.
26+
27+
- `MAJOR`: incompatible curriculum or CLI changes.
28+
- `MINOR`: new topics, exercises, TUI features, or docs workflows.
29+
- `PATCH`: fixes, copy edits, compatible tests, and packaging updates.

0 commit comments

Comments
 (0)