Хичээл 1: README ба Markdown

Танилцуулга

Бүлэг 4-т бид зарлагын бүртгэлээ GitHub руу гаргаж, хоёр газраас аюулгүй ажиллаж сурсан. Одоо таны repository интернэтэд байгаа ч нэг чухал зүйл дутуу байна. Хэн нэгэн таны repository хуудсыг нээхэд файлуудын жагсаалтыг л харна: main.py, report.py, storage.py гэх мэт. Энэ программ юу хийдэг вэ? Яаж ажиллуулах вэ? Юу хэрэгтэй вэ? Энэ асуултуудын хариулт хаана ч бичигдээгүй. Энэ хичээлд бид тэр хоосон зайг README файлаар дүүргэнэ.

README бол repository-ийн нүүр хуудас, таны төслийг нээсэн хүн бүрийн хамгийн түрүүнд уншдаг зүйл юм. GitHub README файлыг файлуудын жагсаалтын доор автоматаар, гоё форматтайгаар харуулдаг. Тэр форматыг Markdown гэдэг энгийн тэмдэглэгээний хэлээр бичдэг. Энэ хичээлд бид эхлээд Markdown-ийн хэрэгтэй бүх хэсгийг нэг нэгээр нь сурна. Дараа нь сайн README ямар асуултуудад хариулдгийг ярилцаж, зарлагын бүртгэлд зориулсан бүрэн README-г алхам алхмаар бичнэ. Эцэст нь түүнийг push хийж, GitHub дээр хэрхэн харагдахыг харна.

Зүйрлэл: номын хавтас ба оршил

Номын дэлгүүрт ном сонгохдоо та шууд дунд хэсгийг нь уншдаггүй. Эхлээд хавтасны нэр, ар талын товч тайлбар, оршлыг нь уншина. Тэр хэдэн мөрөөс ном юуны тухай, хэнд зориулагдсан, танд хэрэгтэй эсэхийг шийднэ. Хавтас, тайлбаргүй ном хэчнээн сайн байсан ч тавиур дээр үл анзаарагдана.

README бол таны төслийн хавтас ба оршил юм. Ажил олгогч, хамтран ажиллах хүсэлтэй хүн, эсвэл таны төслийг ашиглахыг хүссэн хэн ч эхлээд README-г уншиж, цааш үргэлжлүүлэх эсэхээ шийднэ. Хэдэн сарын дараа өөрийн төсөл рүүгээ буцаж ирэх та өөрөө ч README-ээс хамгийн их ашиг хүртэнэ. Учир нь тэр үед төслөө хэрхэн ажиллуулдгаа мартсан байх магадлалтай. Сайн README бол таны кодын өмнөх хамгийн чухал хэдэн мөр юм.

Markdown гэж юу вэ

Markdown бол энгийн текстэд хэдэн тэмдэг нэмж формат өгдөг хэл юм. Word программд гарчиг хийхдээ та товч дардаг бол Markdown-д мөрийн эхэнд “#” тэмдэг бичнэ. Тодруулахдаа “**” тэмдгээр хүрээлнэ. Markdown файл нь ердийн текст файл бөгөөд өргөтгөл нь “.md” байдаг. Түүнийг ямар ч editor-оор нээж уншиж болно, тэмдгүүд нь харагдах ч уншихад саад болохгүй. Харин GitHub, VS Code зэрэг программууд тэр тэмдгүүдийг жинхэнэ гарчиг, жагсаалт, кодын блок болгон харуулдаг.

Markdown хөгжүүлэгчдийн дунд маш өргөн тархсан. README файлаас гадна GitHub-ийн issue, pull request-ийн тайлбар, олон баримт бичиг, тэмдэглэлийн программууд бүгд Markdown хэрэглэдэг. Тиймээс энэ хичээлд сурсан зүйл тань энэ сургалтын цаашдын бүлгүүдэд, мөн ирээдүйн ажилд тань байнга хэрэг болно. Markdown-ийг сурахад хэдхэн минут л хангалттай, учир нь түүнд цөөхөн дүрэм бий.

Бэлтгэл: Markdown-ыг VS Code-д харах

Эхлээд Markdown-аа бичиж байхдаа түүний харагдах байдлыг шууд харах аргыг тохируулъя. Гэрийн компьютерийн expense-tracker фолдероо VS Code-д нээгээд, 4.4 дүгээр хичээлийн дадлаар эхлээд pull хийнэ үү.

Command:

git pull

Гаралт:

Already up to date.

Одоо Explorer хэсэгт төслийн үндсэн фолдерт, main.py-тэй нэг түвшинд README.md нэртэй шинэ файл үүсгэнэ үү. Нэр нь томоор “README”, өргөтгөл нь “.md” байх нь дэлхий нийтийн заншил. Файл нээлттэй байхад Ctrl+Shift+V товчийг зэрэг дарна уу. Шинэ таб дээр Markdown-ийн preview буюу урьдчилан харах хуудас нээгдэнэ. Хэрвээ хоёр табыг зэрэгцүүлж харахыг хүсвэл Ctrl+K товчийг дараад, дараа нь V товчийг дарна уу: файл зүүн талд, preview баруун талд гарна. Ингэснээр бичих бүрт үр дүнг шууд харна.

Markdown-ийн үндсэн хэсгүүд

Одоо Markdown-ийн хэрэгтэй хэсгүүдийг нэг нэгээр нь сурцгаая. Доорх жишээ бүрийг README.md-д түр бичиж, preview-д хэрхэн харагдахыг өөрийн нүдээр хараарай. Дараа нь бүгдийг устгаж, жинхэнэ README-гээ бичнэ.

Гарчиг

Мөрийн эхэнд “#” тэмдэг бичвэл тэр мөр гарчиг болно. “#”-ийн тоо гарчгийн түвшнийг заана: нэг “#” хамгийн том гарчиг, хоёр “##” дэд гарчиг, гурав “###” түүнээс жижиг.

markdown

# Төслийн нэр

## Үндсэн хэсэг

### Дэд хэсэг

Нэг чухал дүрэм: “#” тэмдгийн дараа заавал хоосон зай байх ёстой. “# Нэр” гарчиг болно, “#Нэр” гарчиг болохгүй, зүгээр л “#”-тэй текст хэвээр үлдэнэ. README-д ихэвчлэн нэг “#” гарчиг байдаг, тэр нь төслийн нэр. Бусад хэсгүүд “##”-оор эхэлдэг.

Догол мөр

Ердийн текстийг зүгээр л бичнэ. Хоёр догол мөрийг хооронд нь хоосон мөрөөр тусгаарлана.

markdown

Энэ бол эхний догол мөр.
Энэ мөр эхний догол мөрийн үргэлжлэл болно.

Энэ бол хоёр дахь догол мөр.

Энд Markdown-ийн хамгийн их гайхшрал төрүүлдэг дүрэм бий. Нэг Enter дарж шинэ мөр рүү шилжих нь Markdown-д шинэ мөр үүсгэдэггүй. Дээрх жишээнд эхний хоёр мөр preview-д нэг мөр болж нийлнэ. Шинэ догол мөр эхлүүлэхийн тулд хоосон мөр, өөрөөр хэлбэл хоёр Enter хэрэгтэй. Энэ дүрэм эхэндээ хачин санагдаж болох ч ингэснээр та урт өгүүлбэрийг editor-т хэд хэдэн мөрөнд хувааж бичих боломжтой болдог.

Тодруулах ба налуу

Үгийг хоёр одоор хүрээлбэл тодорно, нэг одоор хүрээлбэл налуу болно.

markdown

Энэ бол **чухал** үг, харин энэ нь *онцолсон* үг.

README-д тодруулалтыг цөөн, үнэхээр чухал зүйлд л ашиглаарай. Хэрвээ бүх зүйл тод байвал юу ч онцгой биш болно.

Жагсаалт

Мөрийн эхэнд “-” тэмдэг болон хоосон зай бичвэл тэмдэгт жагсаалт болно. Мөрийн эхэнд “1.” гэх мэт тоо бичвэл дугаартай жагсаалт болно.

markdown

- Нэгдүгээр зүйл
- Хоёрдугаар зүйл
- Гуравдугаар зүйл

1. Эхний алхам
2. Хоёр дахь алхам
3. Гурав дахь алхам

Дараалал чухал биш зүйлсийг, жишээ нь боломжуудын жагсаалтыг тэмдэгт жагсаалтаар, дараалал чухал зүйлсийг, жишээ нь суулгах алхмуудыг дугаартай жагсаалтаар бичдэг. Жагсаалтын өмнө, ард нь хоосон мөр үлдээвэл ямар ч editor дээр зөв харагдана.

Мөр доторх код

Мөр доторх богино код, файлын нэр, command-ыг нэг ташуу хашилтаар хүрээлнэ. Энэ тэмдэг гарын зүүн дээд буланд, 1-ийн зүүн талд байдаг.

markdown

Программыг эхлүүлэхдээ `main.py` файлыг ажиллуулна.

Preview-д main.py саарал дэвсгэртэй, кодын үсгээр харагдана. Ингэснээр уншигч энэ нь ердийн үг биш, файлын нэр эсвэл код гэдгийг шууд мэднэ.

Кодын блок

Хэд хэдэн мөр кодыг гурван ташуу хашилтаар эхлүүлж, гурваар төгсгөнө. Эхний гурван хашилтын ард хэлний нэрийг бичвэл GitHub кодыг өнгөөр ялгаж харуулна.

markdown

```python
def total(expenses):
    return sum(e["amount"] for e in expenses)
```

Command-уудын хувьд хэлний нэрийг powershell гэж бичнэ. Хэлний нэр бичихгүй бол код өнгөгүй, энгийн кодын фонтоор харагдана, энэ нь программын гаралтыг харуулахад тохиромжтой. Хамгийн чухал дүрэм: кодын блокийг заавал хаах ёстой. Хаах гурван хашилтаа мартвал файлын үлдсэн бүх хэсэг код болж харагдана.

Холбоос

Холбоосыг дөрвөлжин хаалтанд харагдах текст, араас нь энгийн хаалтанд хаяг бичиж үүсгэнэ.

markdown

Дэлгэрэнгүйг [Python-ий албан ёсны сайт](https://www.python.org)-аас үзнэ үү.

Preview-д “Python-ий албан ёсны сайт” гэсэн текст дарж болох холбоос болж харагдана. Дөрвөлжин хаалт болон энгийн хаалтын хооронд хоосон зай байж болохгүй, байвал холбоос ажиллахгүй.

Товч лавлах

Сурсан бүх зүйлээ нэг дор цуглуулъя. Ирээдүйд Markdown бичихдээ энэ жагсаалт руу эргэж хараарай.

markdown

# Том гарчиг
## Дэд гарчиг
**тод**  *налуу*
- тэмдэгт жагсаалт
1. дугаартай жагсаалт
`мөр доторх код`
```python
кодын блок
```
[холбоосын текст](https://хаяг)

Сайн README ямар асуултад хариулдаг вэ

Markdown-ийг мэдсэнээр бид юу бичихээ шийдэх ёстой. Сайн README урт байх албагүй, харин уншигчийн гол асуултуудад тодорхой хариулдаг. Энэ асуултууд төслөөс үл хамааран бараг ижил байдаг.

Нэгдүгээрт, энэ юу вэ? Нэг хоёр өгүүлбэрээр төсөл юу хийдгийг хэлнэ. Уншигч эхний хэдэн секундэд энэ нь өөрт нь хамаатай эсэхийг мэдэх ёстой. Хоёрдугаарт, юу чадах вэ? Гол боломжуудын товч жагсаалт. Энэ нь төслийн хүрээг харуулна. Гуравдугаарт, юу хэрэгтэй вэ? Python-ий хувилбар, гадны package, бусад шаардлага. Дөрөвдүгээрт, яаж ажиллуулах вэ? Төслийг clone хийснээс эхлэн программ ажиллах хүртэлх яг бичих command-ууд. Энэ бол хамгийн чухал хэсэг бөгөөд олон README яг энд дутуу байдаг. Тавдугаарт, юу харагдах вэ? Программын гаралтын жишээ. Уншигч ажиллуулахаасаа өмнө үр дүнг төсөөлж, ажиллуулсны дараа зөв ажилласан эсэхийг харьцуулна.

4.3 дугаар хичээлд хуулбар фолдерт программ ажиллуулахад юу тохиолдсоныг санаарай. Хэрвээ data файлаа .gitignore-д нэмсэн бол хуулбарт FileNotFoundError гарсан. Тэр үед бид “repository-г clone хийсэн хүн юу дутуу байгааг README-ээс мэдэх ёстой” гэж хэлсэн. Одоо яг тэр мэдээллийг бичих цаг ирлээ. "Яаж ажиллуулах вэ" хэсэг бол repository-д байхгүй, гараар бэлдэх ёстой зүйлсийг бичих газар юм.

Нэг шийдвэр бий: README-г ямар хэлээр бичих вэ. Commit message-тэй адил шалтгаанаар энэ сургалтын жишээ README англиар бичигдсэн: таны GitHub-ийг дэлхийн аль ч ажил олгогч уншиж чадна. Гэхдээ энэ бол таны төсөл бөгөөд хэрвээ Монгол уншигчдад зориулж байгаа бол монголоор, эсвэл хоёр хэлээр бичих нь бүрэн зөв. Англи хэлээр бичихдээ урт, нарийн өгүүлбэр шаардлагагүй, энгийн, тодорхой өгүүлбэрүүд хамгийн сайн.

Анхны жишээ: зарлагын бүртгэлийн README

Одоо README.md-ийн доторх бүх туршилтын текстийг устгаад, жинхэнэ README-гээ хэсэг хэсгээр нь бичье. Хэсэг бүрийг бичсний дараа preview-ээр шалгаарай. Таны программ жишээнийхээс өөр бол агуулгыг өөрийн программд тааруулж засаарай.

Хэсэг 1: Нэр ба товч тайлбар

markdown

# Expense Tracker

A simple command-line expense tracker written in Python.
It reads expenses from a JSON file and prints a short summary.

Гарчиг бол төслийн нэр. Доорх хоёр өгүүлбэр "энэ юу вэ" гэсэн асуултад хариулж байна. Хоёр өгүүлбэр хоёр мөрөнд бичигдсэн ч preview-д нэг догол мөр болно, учир нь тэдгээрийн хооронд хоосон мөр байхгүй.

Хэсэг 2: Боломжууд

markdown

## Features

- Prints the total of all expenses, formatted in tugrik (₮)
- Prints the number of expenses
- Includes helper functions for the average and for saving data

Энд нэг шударга зарчим бий: зөвхөн программын жинхэнэ хийдэг зүйлийг бичнэ. Манай программ дундаж тооцоолох функцтэй ч main.py түүнийг хэвлэдэггүй. Тиймээс бид "дундажийг хэвлэдэг" гэж бичээгүй, "туслах функц бий" гэж үнэнээр нь бичсэн. Байхгүй боломжийг README-д бичих нь уншигчийн итгэлийг хамгийн хурдан алдагдуулдаг.

Хэсэг 3: Шаардлага

markdown

## Requirements

- Python 3.10 or newer
- No external packages

Хэрвээ таны программ гадны package ашигладаг бол “No external packages”-ийн оронд requirements.txt-ийн тухай бичнэ. Энэ хэсэг богино ч чухал, учир нь уншигч юу суулгах ёстойг эхнээс нь мэднэ.

Хэсэг 4: Ажиллуулах заавар

markdown

## How to run

Clone the repository and open the folder:

```powershell
git clone https://github.com/bat-dorj/expense-tracker.git
cd expense-tracker
```

Run the program:

```powershell
python main.py
```

Хаягийг өөрийн username-ээр солиорой. Алхам бүрийн өмнө түүнийг юу хийдгийг хэлсэн нэг өгүүлбэр, дараа нь кодын блок байна. Command-ууд кодын блокт байгаа тул уншигч тэдгээрийг шууд хуулж ашиглана.

Хэрвээ та 3.4 дүгээр хичээлд data файлаа .gitignore-д нэмсэн бол энэ хэсэгт, “Run the program”-ийн өмнө нэг алхам нэмэх ёстой. Жишээ нь:

markdown

Create the data file `data/expenses.json` with your expenses:

```json
[
  {"amount": 5000, "category": "food"}
]
```

Энэ бол 4.3 дугаар хичээлд гарсан FileNotFoundError-ийн жинхэнэ шийдэл. Clone хийсэн хүн юу дутуу байгааг яг энд олж, алдаа гарахаас өмнө бэлдэнэ.

Хэсэг 5: Гаралтын жишээ

markdown

Example output:

```
Нийт зарлага: 20,500₮
Нийт бичлэг: 3 ширхэг
```

Энэ кодын блок хэлний нэргүй, учир нь энэ бол код биш, программын гаралт. Энд таны программын жинхэнэ гаралтыг terminal-аас хуулж тавина уу.

Хэсэг 6: Төслийн бүтэц

markdown

## Project structure

- `main.py` — entry point, prints the summary
- `storage.py` — loading and saving expenses
- `report.py` — total, count and average
- `formatting.py` — money formatting
- `data/expenses.json` — sample data

Энэ хэсэг сонголт боловч олон файлтай төсөлд маш тустай. Уншигч кодыг нээхээсээ өмнө аль файл юу хийдгийг мэднэ. Файлын нэрс мөр доторх кодын тэмдэгтэй тул тод ялгарч харагдана.

Бүрэн README

Бүх хэсгийг нэгтгэвэл таны README дараах байдалтай болно.

markdown

# Expense Tracker

A simple command-line expense tracker written in Python.
It reads expenses from a JSON file and prints a short summary.

## Features

- Prints the total of all expenses, formatted in tugrik (₮)
- Prints the number of expenses
- Includes helper functions for the average and for saving data

## Requirements

- Python 3.10 or newer
- No external packages

## How to run

Clone the repository and open the folder:

```powershell
git clone https://github.com/bat-dorj/expense-tracker.git
cd expense-tracker
```

Run the program:

```powershell
python main.py
```

Example output:

```
Нийт зарлага: 20,500₮
Нийт бичлэг: 3 ширхэг
```

## Project structure

- `main.py` — entry point, prints the summary
- `storage.py` — loading and saving expenses
- `report.py` — total, count and average
- `formatting.py` — money formatting
- `data/expenses.json` — sample data

Хадгалаад preview-ийг сүүлчийн удаа шалгаарай. Гарчгууд том, жагсаалтууд цэгтэй, кодын блокууд саарал хайрцагт, файлын нэрс кодын фонтоор харагдах ёстой. Хэрвээ аль нэг хэсэг хачин харагдвал түгээмэл алдаанууд хэсгийг хараарай.

Commit ба push

Command:

git add README.md
git commit -m "Add README"
git push

Гаралт (сүүлийн мөрүүд):

[main 7c4e9a2] Add README
 1 file changed, 41 insertions(+)
 create mode 100644 README.md
...
To https://github.com/bat-dorj/expense-tracker.git
   d6b1f83..7c4e9a2  main -> main

Таны мөрийн тоо болон hash өөр байна. Одоо browser дээр GitHub-ийн repository хуудсаа дахин ачаална уу. Файлуудын жагсаалтын доор таны README бүрэн форматтайгаар харагдана: том гарчиг, жагсаалтууд, өнгөт кодын блокууд. Таны repository одоо өөрийгөө танилцуулдаг боллоо.

[Зураг: README харагдаж буй GitHub repository хуудас]

Туршаад үзээрэй

Хүсвэл GitHub дээр өөрийн дуртай, сайн мэдэх Python package-ийн repository-г нээж README-г нь уншаарай, жишээ нь requests эсвэл rich. Тэдгээрийн README-д бидний ярьсан асуултуудын хариулт хэрхэн бичигдсэнийг ажиглаарай: товч тайлбар, суулгах заавар, жишээ код. Дараа нь тэр README-ийн дээд хэсэгт байх “README.md” файлын нэр дээр дарж, баруун дээд талын “Raw” товчийг дарвал Markdown-ийн түүхий текстийг харна. Мэргэжлийн README ч яг таны сурсан тэмдгүүдээр бичигддэгийг харах сонирхолтой.

Түгээмэл алдаанууд

Гарчиг гарчиг болохгүй байх. Хамгийн түгээмэл шалтгаан нь “#” тэмдгийн дараа хоосон зай байхгүй явдал. “##Features” гэж бичвэл preview-д “##Features” гэсэн энгийн текст харагдана. “## Features” гэж зайтай бичнэ үү.

Хоёр догол мөр нийлэх. Хэрвээ та хоёр өөр санааг хоёр мөрөнд бичсэн хэрнээ preview-д нэг урт мөр болон харагдаж байвал тэдгээрийн хооронд хоосон мөр нэмнэ үү. Markdown-д нэг Enter шинэ мөр үүсгэдэггүй, шинэ догол мөрөнд хоосон мөр хэрэгтэй.

Файлын үлдсэн хэсэг код болох. Хэрвээ preview-д кодын блокоос хойших бүх текст саарал хайрцагт, кодын фонтоор харагдаж байвал кодын блокийн хаах гурван ташуу хашилт дутуу байна. Кодын блок бүрийн эхлэл болон төгсгөлийн хашилтуудыг тоолж шалгаарай, тэд хосоороо байх ёстой. Мөн гурван ташуу хашилтын оронд дан хашилт эсвэл “‘” тэмдэг бичигдсэн эсэхийг шалгаарай.

Холбоос ажиллахгүй байх. Дөрвөлжин хаалт болон энгийн хаалтын хооронд хоосон зай байгаа эсэхийг шалгаарай: “[текст] (хаяг)” буруу, “текст” зөв. Мөн хаяг “https://”-ээр эхэлсэн эсэхийг шалгаарай.

GitHub README-г харуулахгүй байх. Хэрвээ push хийсэн ч GitHub файлуудын доор README харуулахгүй байвал гурван шалтгаан байж болно. Нэгдүгээрт, файлын нэр буруу: Notepad-аар үүсгэсэн бол “README.md.txt” болсон байж болно, VS Code-ийн Explorer-оос нэрийг шалгаарай. Хоёрдугаарт, файл дэд фолдерт байна: README төслийн үндсэн фолдерт байх ёстой. Гуравдугаарт, push хийгээгүй: git status “ahead” гэж хэлж байгаа эсэхийг шалгаарай.

Кирилл үсэг preview-д хачин харагдах. Хэрвээ README-ийн кирилл текст утгагүй тэмдэгт болон харагдвал файл UTF-8 кодчилолоор хадгалагдаагүй байна. Энэ нь файлыг VS Code-оос гадуур, жишээ нь PowerShell-ээр үүсгэсэн үед тохиолддог. VS Code-ийн доод мөрөнд кодчилолын нэр харагддаг, тэр нь “UTF-8” байх ёстой. Хэрвээ өөр байвал түүн дээр дарж “Save with Encoding”, дараа нь “UTF-8”-ийг сонгоно уу.

Товч дүгнэлт

README.md бол repository-ийн нүүр хуудас бөгөөд GitHub түүнийг файлуудын доор автоматаар харуулдаг. Markdown бол энгийн текстэд формат өгдөг хэл: “#” гарчиг (араас нь заавал зай), хоосон мөр шинэ догол мөр, “**” тод, “*” налуу, “-” тэмдэгт жагсаалт, “1.” дугаартай жагсаалт, нэг ташуу хашилт мөр доторх код, гурван ташуу хашилт кодын блок (заавал хаана), “текст” холбоос. VS Code-д Ctrl+Shift+V preview-ийг нээнэ. Сайн README юу вэ, юу чадах вэ, юу хэрэгтэй вэ, яаж ажиллуулах вэ, юу харагдах вэ гэсэн асуултуудад хариулдаг. Зөвхөн программын жинхэнэ хийдэг зүйлийг бичиж, repository-д ороогүй ч ажиллахад шаардлагатай зүйлсийг ажиллуулах зааварт тодорхой бичнэ.

Дараагийн хичээлд repository-гийнхоо бусад хэсгийг цэгцэлнэ. Мэргэжлийн төслийн фолдерын бүтэц, өмнөх сургалтаас санаж буй requirements.txt, мөн LICENSE файлын тухай ярина. Цэгцгүй repository-г цэгцтэй болгох "өмнө ба дараа" жишээг алхам алхмаар харна.