diff --git a/Doxyfile b/Doxyfile index 4248036..66ccc09 100644 --- a/Doxyfile +++ b/Doxyfile @@ -32,7 +32,7 @@ INLINE_INHERITED_MEMB = NO FULL_PATH_NAMES = YES STRIP_FROM_PATH = STRIP_FROM_INC_PATH = -SHORT_NAMES = NO +SHORT_NAMES = YES JAVADOC_AUTOBRIEF = NO JAVADOC_BANNER = NO QT_AUTOBRIEF = NO @@ -130,10 +130,10 @@ WARN_LOGFILE = #--------------------------------------------------------------------------- # Configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = src README.md +INPUT = src INPUT_ENCODING = UTF-8 INPUT_FILE_ENCODING = -FILE_PATTERNS = *.py *.md +FILE_PATTERNS = *.py RECURSIVE = YES EXCLUDE = EXCLUDE_SYMLINKS = NO @@ -147,7 +147,7 @@ INPUT_FILTER = FILTER_PATTERNS = FILTER_SOURCE_FILES = NO FILTER_SOURCE_PATTERNS = -USE_MDFILE_AS_MAINPAGE = README.md +USE_MDFILE_AS_MAINPAGE = IMPLICIT_DIR_DOCS = YES FORTRAN_COMMENT_AFTER = 72 #--------------------------------------------------------------------------- diff --git a/README.md b/README.md index 7c00f4e..58254f6 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,206 @@ -# 026-nato-alphabet +# 🚀 NATO alphabet +A console tool that spells a word with the NATO phonetic alphabet, the Day 26 assignment of Udemy's "100 Days of Code: The Complete Python Pro Bootcamp". It is written for fellow course participants and GitHub visitors who want a readable, tested, runnable solution that uses list and dictionary comprehensions and has no runtime dependencies. + +![The tool spelling the word Hello][screenshot-spell] + +## 📚 Table of Contents + +- [Overview](#-overview) +- [Requirements](#-requirements) +- [Setup](#-setup) +- [Run](#-run) +- [Tests](#-tests) +- [Continuous integration](#-continuous-integration) +- [Build the source documentation](#-build-the-source-documentation) +- [Project layout](#-project-layout) +- [License](#-license) +- [Links](#-links) +- [Appendix: Project documents](#-appendix-project-documents) + +## 🧭 Overview + +You type a word, the program prints the NATO code word of each letter. A character that is not a letter makes it ask again. + +```text +Enter a word: Hello +Phonetic code words: +Hotel +Echo +Lima +Lima +Oscar +``` + +How it works, in the course's terms: + +- `load_nato_dict` reads the supplied CSV file and builds the letter-to-code-word dictionary with a **dictionary comprehension**. +- `generate_phonetic` turns a word into its code words with a **list comprehension**. +- The standard library `csv` module replaces Pandas, so the project has no runtime dependencies (see the architecture decision record [ADR-0001][ADR-0001]). + +The wiki explains installation, usage and development in English, Danish and Bahasa Malaysia: [wiki][wiki]. + +## 📋 Requirements + +- Python 3.13 or newer, with the `venv` module. +- Git, to clone the repository. +- Optional: [Doxygen](https://www.doxygen.nl/) to build the source documentation. + +The program itself needs no packages. The development tools (pytest, ruff, mypy, import-linter) are installed by the `dev` extra. + +## 🛠️ Setup + +Clone the repository, then create a local virtual environment named `.venv` in its root, upgrade pip and install the project in editable mode with its development tools. + +### Windows PowerShell + +```powershell +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +py -3.13 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +If PowerShell refuses to run the activation script, allow it for this window only with `Set-ExecutionPolicy -Scope Process RemoteSigned`. + +### Linux Debian + +```bash +sudo apt install git python3 python3-venv +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +Debian 13 (trixie) ships Python 3.13. On an older release install Python 3.13 first (for example with `pyenv`). + +### MacOS + +```bash +brew install python@3.13 git +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +python3.13 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +## ▶️ Run + +With the virtual environment active: + +```bash +python -m nato_alphabet +``` + +or, as the installed command: + +```bash +nato-alphabet +``` + +An invalid character asks for the word again: + +![A word with a digit is rejected, then a valid word is spelled][screenshot-retry] + +## 🧪 Tests + +Run the tests with the virtual environment active: + +```bash +python -m pytest +``` + +The same checks that CI runs: + +```bash +python -m ruff check . +python -m mypy +lint-imports +``` + +## 🔄 Continuous integration + +The workflow [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml) runs on every push to `main` or a `mil-*` branch and on every pull request that touches source, tests or configuration. It sets up Python 3.13, creates a virtual environment, installs the project with the `dev` extra, and runs ruff, mypy and pytest. + +## 📖 Build the source documentation + +The source is documented with Doxygen comments. From the repository root: + +```bash +doxygen Doxyfile +``` + +Open `build/html/index.html` in a browser. The `build/` folder is ignored by git. + +## 🗂️ Project layout + +```text +src/nato_alphabet/ + constants.py every literal of the program + main.py composition root and entry point + __main__.py python -m nato_alphabet + domain/ the spelling rule (no input or output) + application/ the use case and its ports + adapters/ CSV reader and console + data/ nato_phonetic_alphabet.csv +tests/ pytest tests, mirroring src/ +docs/ project documents (see the appendix) +wiki/ wiki pages in en, da and ms +.gitea/workflows/ CI workflow +pyproject.toml project configuration +Doxyfile Doxygen configuration +``` + +## 📄 License + +GNU Affero General Public License v3.0 or later. See [LICENSE](LICENSE). + +## 🔗 Links + +- [Repository][repository] +- [Documentation][documentation] +- [Issue tracker][issues] + +## 📎 Appendix: Project documents + +The documents a newcomer needs, in reading order. + +| Document | What it tells you | +| --- | --- | +| [AGENTS.md][agents] | The rules AI agents follow in this repository | +| [Business Case][BC-001] | Why the project exists, its scope and success criteria | +| [Stakeholder Analysis][SA-001] | Who is involved; the stakeholder IDs used for owners and reviewers | +| [Project Plan][PP-001] | The gateways and their schedule | +| [Milestones][milestones] | One document per gateway: Go/No-Go criteria and tasks | +| [Architecture decisions][adr] | Why the data is read with the standard library and which analysis documents were skipped | +| [Artifact registry][registry] | Where each artifact type lives, the next version, the PO language and domain | +| [Traceability matrix][TM-001] | How the artifacts link and when each was last reviewed | +| [Framework README][framework-readme] | The framework this project uses | +| [Framework changelog][framework-changelog] | What changed in each framework release | + +--- + +[repository]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet +[documentation]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet/wiki +[wiki]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet/wiki +[issues]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet/issues +[screenshot-spell]: ./docs/images/spell-word.png +[screenshot-retry]: ./docs/images/retry-invalid.png +[agents]: ./AGENTS.md +[BC-001]: ./docs/business-case.md +[SA-001]: ./docs/stakeholder-analysis.md +[PP-001]: ./docs/project-plan.md +[milestones]: ./docs/milestones/ +[adr]: ./docs/adr/ +[ADR-0001]: ./docs/adr/adr-0001-read-nato-data-with-csv-module.md +[registry]: ./docs/artifact-registry.md +[TM-001]: ./docs/sqa/traceability-matrix.md +[framework-readme]: ./framework/README.md +[framework-changelog]: ./framework/CHANGELOG.md diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 23e096e..bc66611 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -15,7 +15,7 @@ document of a type. `Primary File` may contain a glob (e.g. | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | | PP | Project Plan | docs/project-plan.md | 002 | | MIL | Milestone / Gateway | docs/milestones/*.md | 004 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 015 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 016 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0003 | | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 | diff --git a/docs/images/retry-invalid.png b/docs/images/retry-invalid.png new file mode 100644 index 0000000..a0994f0 Binary files /dev/null and b/docs/images/retry-invalid.png differ diff --git a/docs/images/spell-word.png b/docs/images/spell-word.png new file mode 100644 index 0000000..64b0214 Binary files /dev/null and b/docs/images/spell-word.png differ diff --git a/docs/sqa/reviews/rc-015-python-package-docs.md b/docs/sqa/reviews/rc-015-python-package-docs.md new file mode 100644 index 0000000..fc18164 --- /dev/null +++ b/docs/sqa/reviews/rc-015-python-package-docs.md @@ -0,0 +1,60 @@ +# SQA Review Record RC-015: PY-003 + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-015 | +| CrossReference | [PY-003], [QC-PY-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Review of PY-003 | [92b9543] | + +--- + +## Artifact Under Review + +- Instance reviewed: [PY-003] +- Checklist used: [QC-PY-001] +- Scope: full review +- Language and domain: n/a (technical type) +- Language reviewer: none +- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | ruff rule set N passes; modules snake_case, classes PascalCase, `InvalidWordError` ends in Error. | +| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names state purpose: `generate_phonetic`, `load_nato_dict`, `SpellWordSession`. | +| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | ruff 0.17.0 check and format pass; no suppressions. | +| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | All signatures annotated; mypy --strict passes. | +| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | `InvalidWordError` is raised `from` the KeyError; the console adapter maps only EOFError and KeyboardInterrupt to `InputClosedError`; no bare except. | +| 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults; `path` defaults to None. | +| 7 | Files, locks and connections are managed with context managers | Pass | The CSV is read inside a `with` block. | +| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | Every module, class, function and constant has a Doxygen docstring; doxygen reports 0 warnings. | +| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | Pass | `print` and `input` are confined to `adapters/console.py` because the console is the program's output; there is no logging and no secret or personal data. | +| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | N-A | No design class diagram exists; MIL-002 plans none (the SSD and use case are the design artifacts). Classes follow the ports in `application/ports.py`. | +| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | 50 tests named for behaviour; `tmp_path` and fakes; no network; order independent. | +| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | Pass | mypy --strict: no issues in 18 files; no `Any`. | +| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | No runtime dependencies; development tools pinned with `==`. | +| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | Each literal is defined once in `constants.py`; the letter mapping is defined once in the CSV. | +| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | import-linter contract `Dependencies point inward` is kept; no cycles. | +| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | Ports are narrow Protocols; the session depends on them, adapters implement them. | + +## Overall Verdict + +Go — re-review of the package after MIL-003 changed only the package docstring (Doxygen main page) and the Doxyfile (`INPUT = src`, `SHORT_NAMES = YES`); the checks are repeated: pytest 50 passed, ruff, mypy --strict, import-linter and doxygen (0 warnings) pass, also in a fresh clone on Windows PowerShell. The README is checked with check-readme.sh (no QC checklist exists for it). + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| None | S01 | n/a | + +--- + +[PY-003]: ../../../src/nato_alphabet/__init__.py +[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md +[92b9543]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet/commit/92b954331c2deb7f9f641eb6266007496b404356 diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index 4cefe67..f8fbaef 100644 --- a/docs/sqa/traceability-matrix.md +++ b/docs/sqa/traceability-matrix.md @@ -9,8 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-13 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added rows for ADR-0001, ADR-0002, the CI workflow and the Python skeleton (RC-006 to RC-009) | [a381791] | -| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added rows for the MIL-002 use case artifacts and converter code (RC-010 to RC-014) | [1b7da4b] | +| 2026-10-13 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added rows for the MIL-002 use case artifacts and converter code (RC-010 to RC-014) | [1b7da4b] | +| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added the package re-review row (RC-015) | [92b9543] | --- @@ -41,7 +41,8 @@ Tracks backward and forward links between artifact instances so that the cross-a | [US-001] | User Story | en | it | [UCD-001], [MIL-002] | [UC-001] | [RC-011] | | [UC-001] | Use Case | en | it | [UCD-001], [US-001] | [SSD-001], [PY-002] | [RC-012] | | [SSD-001] | System Sequence Diagram | en | it | [UC-001] | [PY-002] | [RC-013] | -| [PY-002] | Python source | - | - | [UC-001], [SSD-001], [ADR-0001] | - | [RC-014] | +| [PY-002] | Python source | - | - | [UC-001], [SSD-001], [ADR-0001] | [PY-003] | [RC-014] | +| [PY-003] | Python source | - | - | [PY-002], [MIL-003] | - | [RC-015] | | [PY-001] | Python source | - | - | [ADR-0001], [MIL-001] | - | [RC-009] | ## Coverage Notes @@ -85,3 +86,6 @@ Tracks backward and forward links between artifact instances so that the cross-a [RC-013]: ./reviews/rc-013-ssd-001.md [RC-014]: ./reviews/rc-014-python-converter.md [1b7da4b]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet/commit/1b7da4bcf95f69bf009b0a1f3d0ab740ae77e340 +[PY-003]: ../../src/nato_alphabet/__init__.py +[RC-015]: ./reviews/rc-015-python-package-docs.md +[92b9543]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet/commit/92b954331c2deb7f9f641eb6266007496b404356 diff --git a/src/nato_alphabet/__init__.py b/src/nato_alphabet/__init__.py index d823b9a..ceb2924 100644 --- a/src/nato_alphabet/__init__.py +++ b/src/nato_alphabet/__init__.py @@ -1 +1,9 @@ -"""@brief Console tool that spells a word with the NATO phonetic alphabet.""" +"""@brief Console tool that spells a word with the NATO phonetic alphabet. + +@mainpage NATO alphabet + +The Day 26 assignment of "100 Days of Code: The Complete Python Pro Bootcamp". +`load_nato_dict` builds the letter-to-code-word dictionary with a dictionary +comprehension and `generate_phonetic` spells a word with a list comprehension. +Run it with `python -m nato_alphabet`. +""" diff --git a/wiki/Development-da.md b/wiki/Development-da.md new file mode 100644 index 0000000..75390ac --- /dev/null +++ b/wiki/Development-da.md @@ -0,0 +1,43 @@ +# Udvikling + +🌐 [English](Development) · **Dansk** · [Bahasa Melayu](Development-ms) + +Sæt projektet op først ([Installation](Install-da)). Udvidelsen `dev` installerer pytest, ruff, mypy og import-linter. + +## Kør testene + +```bash +python -m pytest +``` + +## Kør de kontroller, CI kører + +```bash +python -m ruff check . +python -m mypy +lint-imports +``` + +## Byg kildedokumentationen + +```bash +doxygen Doxyfile +``` + +Åbn `build/html/index.html`. Installér Doxygen fra [doxygen.nl](https://www.doxygen.nl/) eller din pakkehåndtering. + +## Kodens opbygning + +| Mappe | Indhold | +| --- | --- | +| `src/nato_alphabet/domain/` | Staveregelen, uden input og output | +| `src/nato_alphabet/application/` | Use casen og dens porte | +| `src/nato_alphabet/adapters/` | CSV-læseren og konsollen | +| `src/nato_alphabet/constants.py` | Alle programmets konstanter | +| `tests/` | pytest-tests, som spejler `src/` | + +Afhængigheder peger indad: adapters kender applikationen, applikationen kender domænet. import-linter håndhæver det. + +## Pull requests + +Én gren og én pull request pr. milepæl; CI skal være grøn. Projektet følger SQA- og QC-frameworket i `framework/`; se `docs/` for planen og review-optegnelserne. diff --git a/wiki/Development-ms.md b/wiki/Development-ms.md new file mode 100644 index 0000000..60e085b --- /dev/null +++ b/wiki/Development-ms.md @@ -0,0 +1,43 @@ +# Pembangunan + +🌐 [English](Development) · [Dansk](Development-da) · **Bahasa Melayu** + +Sediakan projek dahulu ([Pemasangan](Install-ms)). Pilihan tambahan `dev` memasang pytest, ruff, mypy dan import-linter. + +## Jalankan ujian + +```bash +python -m pytest +``` + +## Jalankan semakan yang dijalankan oleh CI + +```bash +python -m ruff check . +python -m mypy +lint-imports +``` + +## Bina dokumentasi sumber + +```bash +doxygen Doxyfile +``` + +Buka `build/html/index.html`. Pasang Doxygen dari [doxygen.nl](https://www.doxygen.nl/) atau pengurus pakej anda. + +## Susun atur kod + +| Folder | Kandungan | +| --- | --- | +| `src/nato_alphabet/domain/` | Peraturan ejaan, tanpa input dan output | +| `src/nato_alphabet/application/` | Kes guna dan portnya | +| `src/nato_alphabet/adapters/` | Pembaca CSV dan konsol | +| `src/nato_alphabet/constants.py` | Semua pemalar program | +| `tests/` | Ujian pytest, mencerminkan `src/` | + +Kebergantungan menghala ke dalam: adapter mengenali aplikasi, aplikasi mengenali domain. import-linter menguatkuasakannya. + +## Pull request + +Satu cabang dan satu pull request bagi setiap milestone; CI mesti hijau. Projek ini mengikut rangka kerja SQA dan QC dalam `framework/`; lihat `docs/` untuk pelan dan rekod semakan. diff --git a/wiki/Development.md b/wiki/Development.md new file mode 100644 index 0000000..3a60c80 --- /dev/null +++ b/wiki/Development.md @@ -0,0 +1,43 @@ +# Development + +🌐 **English** · [Dansk](Development-da) · [Bahasa Melayu](Development-ms) + +Set up the project first ([Install](Install)). The `dev` extra installs pytest, ruff, mypy and import-linter. + +## Run the tests + +```bash +python -m pytest +``` + +## Run the checks that CI runs + +```bash +python -m ruff check . +python -m mypy +lint-imports +``` + +## Build the source documentation + +```bash +doxygen Doxyfile +``` + +Open `build/html/index.html`. Install Doxygen from [doxygen.nl](https://www.doxygen.nl/) or your package manager. + +## Code layout + +| Folder | Content | +| --- | --- | +| `src/nato_alphabet/domain/` | The spelling rule, with no input or output | +| `src/nato_alphabet/application/` | The use case and its ports | +| `src/nato_alphabet/adapters/` | The CSV reader and the console | +| `src/nato_alphabet/constants.py` | Every literal of the program | +| `tests/` | pytest tests, mirroring `src/` | + +Dependencies point inward: adapters know the application, the application knows the domain. import-linter enforces it. + +## Pull requests + +One branch and one pull request per milestone; CI must be green. The project follows the SQA and QC framework in `framework/`; see `docs/` for the plan and the review records. diff --git a/wiki/Home-da.md b/wiki/Home-da.md new file mode 100644 index 0000000..b4e7665 --- /dev/null +++ b/wiki/Home-da.md @@ -0,0 +1,23 @@ +# NATO-alfabet + +🌐 [English](Home) · **Dansk** · [Bahasa Melayu](Home-ms) + +Et konsolprogram, der staver et ord med det fonetiske NATO-alfabet. Det er opgaven fra dag 26 i Udemys "100 Days of Code: The Complete Python Pro Bootcamp" og viser list comprehensions og dictionary comprehensions. Det kræver Python 3.13 eller nyere og har ingen runtime-afhængigheder. + +![Programmet staver ordet Hello](images/spell-word.png) + +| Side | Læs den, når du vil | +| --- | --- | +| [Installation](Install-da) | Oprette et lokalt `.venv` og installere projektet på Windows, Linux eller macOS | +| [Brug](Usage-da) | Køre programmet og læse dets output | +| [Udvikling](Development-da) | Køre testene og kontrollerne og bygge kildedokumentationen | + +## Hvem det er til + +- **Kursister**, der vil have en læsbar løsning med opgavens funktionsnavne (`load_nato_dict`, `generate_phonetic`) at sammenligne med deres egen. +- **GitHub-besøgende**, der vil se et lille, testet Python-projekt uden runtime-afhængigheder. + +## Links + +- [Repository](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet) +- [Fejl og ønsker](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet/issues) diff --git a/wiki/Home-ms.md b/wiki/Home-ms.md new file mode 100644 index 0000000..cc30d9f --- /dev/null +++ b/wiki/Home-ms.md @@ -0,0 +1,23 @@ +# Abjad NATO + +🌐 [English](Home) · [Dansk](Home-da) · **Bahasa Melayu** + +Alat konsol yang mengeja satu perkataan dengan abjad fonetik NATO. Ia ialah tugasan hari ke-26 dalam "100 Days of Code: The Complete Python Pro Bootcamp" di Udemy dan menunjukkan list comprehension serta dictionary comprehension. Ia memerlukan Python 3.13 atau lebih baharu dan tidak mempunyai kebergantungan masa jalan. + +![Alat mengeja perkataan Hello](images/spell-word.png) + +| Halaman | Baca apabila anda mahu | +| --- | --- | +| [Pemasangan](Install-ms) | Mencipta `.venv` setempat dan memasang projek di Windows, Linux atau macOS | +| [Penggunaan](Usage-ms) | Menjalankan program dan membaca outputnya | +| [Pembangunan](Development-ms) | Menjalankan ujian dan semakan serta membina dokumentasi sumber | + +## Untuk siapa + +- **Peserta kursus** yang mahukan penyelesaian yang mudah dibaca dengan nama fungsi tugasan (`load_nato_dict`, `generate_phonetic`) untuk dibandingkan dengan penyelesaian sendiri. +- **Pelawat GitHub** yang mahukan projek Python kecil yang diuji tanpa kebergantungan masa jalan. + +## Pautan + +- [Repositori](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet) +- [Penjejak isu](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet/issues) diff --git a/wiki/Home.md b/wiki/Home.md new file mode 100644 index 0000000..87ef8db --- /dev/null +++ b/wiki/Home.md @@ -0,0 +1,23 @@ +# NATO alphabet + +🌐 **English** · [Dansk](Home-da) · [Bahasa Melayu](Home-ms) + +A console tool that spells a word with the NATO phonetic alphabet. It is the Day 26 assignment of Udemy's "100 Days of Code: The Complete Python Pro Bootcamp" and shows list and dictionary comprehensions. It needs Python 3.13 or newer and has no runtime dependencies. + +![The tool spelling the word Hello](images/spell-word.png) + +| Page | Read it when you want to | +| --- | --- | +| [Install](Install) | Create a local `.venv` and install the project on Windows, Linux or macOS | +| [Usage](Usage) | Run the program and read its output | +| [Development](Development) | Run the tests, the checks and build the source documentation | + +## Who it is for + +- **Course participants** who want a readable solution with the assignment's function names (`load_nato_dict`, `generate_phonetic`) to compare with their own. +- **GitHub viewers** who want a small, tested Python project with no runtime dependencies. + +## Links + +- [Repository](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet) +- [Issue tracker](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet/issues) diff --git a/wiki/Install-da.md b/wiki/Install-da.md new file mode 100644 index 0000000..6364ed7 --- /dev/null +++ b/wiki/Install-da.md @@ -0,0 +1,57 @@ +# Installation + +🌐 [English](Install) · **Dansk** · [Bahasa Melayu](Install-ms) + +## Det skal du bruge + +- Python 3.13 eller nyere med modulet `venv` +- Git + +## Trin + +Alle systemer gør de samme fire ting: klon repository'et, opret et virtuelt miljø kaldet `.venv`, opgradér pip og installér projektet. + +### Windows PowerShell + +```powershell +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +py -3.13 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +Hvis PowerShell afviser aktiveringsscriptet, så kør først `Set-ExecutionPolicy -Scope Process RemoteSigned`. Det gælder kun for det vindue. + +### Linux Debian + +```bash +sudo apt install git python3 python3-venv +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +### macOS + +```bash +brew install python@3.13 git +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +python3.13 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +## Tjek at det virker + +```bash +python -m nato_alphabet +``` + +Skriv et ord. Du skal se dets kodeord. Næste side: [Brug](Usage-da). diff --git a/wiki/Install-ms.md b/wiki/Install-ms.md new file mode 100644 index 0000000..f71d540 --- /dev/null +++ b/wiki/Install-ms.md @@ -0,0 +1,57 @@ +# Pemasangan + +🌐 [English](Install) · [Dansk](Install-da) · **Bahasa Melayu** + +## Apa yang diperlukan + +- Python 3.13 atau lebih baharu dengan modul `venv` +- Git + +## Langkah + +Semua sistem melakukan empat perkara yang sama: klon repositori, cipta persekitaran maya bernama `.venv`, naik taraf pip dan pasang projek. + +### Windows PowerShell + +```powershell +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +py -3.13 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +Jika PowerShell enggan menjalankan skrip pengaktifan, jalankan `Set-ExecutionPolicy -Scope Process RemoteSigned` dahulu. Ia hanya terpakai pada tetingkap itu. + +### Linux Debian + +```bash +sudo apt install git python3 python3-venv +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +### macOS + +```bash +brew install python@3.13 git +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +python3.13 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +## Semak ia berfungsi + +```bash +python -m nato_alphabet +``` + +Masukkan satu perkataan. Anda akan melihat kata kodnya. Seterusnya: [Penggunaan](Usage-ms). diff --git a/wiki/Install.md b/wiki/Install.md new file mode 100644 index 0000000..0dd6285 --- /dev/null +++ b/wiki/Install.md @@ -0,0 +1,57 @@ +# Install + +🌐 **English** · [Dansk](Install-da) · [Bahasa Melayu](Install-ms) + +## What you need + +- Python 3.13 or newer with the `venv` module +- Git + +## Steps + +Every system does the same four things: clone the repository, create a virtual environment called `.venv`, upgrade pip, install the project. + +### Windows PowerShell + +```powershell +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +py -3.13 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +If PowerShell refuses to run the activation script, run `Set-ExecutionPolicy -Scope Process RemoteSigned` first. It only applies to that window. + +### Linux Debian + +```bash +sudo apt install git python3 python3-venv +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +### macOS + +```bash +brew install python@3.13 git +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet.git +cd 026-nato-alphabet +python3.13 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +## Check that it works + +```bash +python -m nato_alphabet +``` + +Enter a word. You should see its code words. Next: [Usage](Usage). diff --git a/wiki/Usage-da.md b/wiki/Usage-da.md new file mode 100644 index 0000000..b0bc38b --- /dev/null +++ b/wiki/Usage-da.md @@ -0,0 +1,31 @@ +# Brug + +🌐 [English](Usage) · **Dansk** · [Bahasa Melayu](Usage-ms) + +Aktivér det virtuelle miljø (se [Installation](Install-da)), og start programmet: + +```bash +python -m nato_alphabet +``` + +Den installerede kommando gør det samme: + +```bash +nato-alphabet +``` + +## Stav et ord + +Programmet spørger efter et ord og skriver NATO-kodeordet for hvert bogstav i rækkefølge. Store og små bogstaver giver samme resultat. + +![Programmet staver ordet Hello](images/spell-word.png) + +## Ugyldigt input + +Et ciffer, et mellemrum eller et tegn er ikke et bogstav. Programmet siger det og spørger igen. + +![Et ord med et ciffer afvises, derefter staves et gyldigt ord](images/retry-invalid.png) + +## Tryk Ctrl+C eller Ctrl+D + +Afslutter du inputtet (Ctrl+D på Linux og macOS, Ctrl+Z og Enter på Windows) eller trykker Ctrl+C, lukker programmet stille. diff --git a/wiki/Usage-ms.md b/wiki/Usage-ms.md new file mode 100644 index 0000000..57454df --- /dev/null +++ b/wiki/Usage-ms.md @@ -0,0 +1,31 @@ +# Penggunaan + +🌐 [English](Usage) · [Dansk](Usage-da) · **Bahasa Melayu** + +Aktifkan persekitaran maya (lihat [Pemasangan](Install-ms)), kemudian mulakan program: + +```bash +python -m nato_alphabet +``` + +Arahan yang dipasang melakukan perkara yang sama: + +```bash +nato-alphabet +``` + +## Eja satu perkataan + +Program meminta satu perkataan dan mencetak kata kod NATO bagi setiap huruf mengikut urutan. Huruf besar dan huruf kecil memberi keputusan yang sama. + +![Alat mengeja perkataan Hello](images/spell-word.png) + +## Input tidak sah + +Angka, ruang atau tanda baca bukan huruf. Program memberitahu perkara itu dan bertanya semula. + +![Perkataan dengan angka ditolak, kemudian perkataan yang sah dieja](images/retry-invalid.png) + +## Tekan Ctrl+C atau Ctrl+D + +Menamatkan input (Ctrl+D di Linux dan macOS, Ctrl+Z kemudian Enter di Windows) atau menekan Ctrl+C menutup program dengan senyap. diff --git a/wiki/Usage.md b/wiki/Usage.md new file mode 100644 index 0000000..e495c98 --- /dev/null +++ b/wiki/Usage.md @@ -0,0 +1,31 @@ +# Usage + +🌐 **English** · [Dansk](Usage-da) · [Bahasa Melayu](Usage-ms) + +Activate the virtual environment (see [Install](Install)), then start the program: + +```bash +python -m nato_alphabet +``` + +The installed command does the same: + +```bash +nato-alphabet +``` + +## Spell a word + +The program asks for a word and prints the NATO code word of each letter, in order. Upper and lower case give the same result. + +![The tool spelling the word Hello](images/spell-word.png) + +## Invalid input + +A digit, a space or a punctuation mark is not a letter. The program says so and asks again. + +![A word with a digit is rejected, then a valid word is spelled](images/retry-invalid.png) + +## Press Ctrl+C or Ctrl+D + +Ending the input (Ctrl+D on Linux and macOS, Ctrl+Z then Enter on Windows) or pressing Ctrl+C closes the program quietly. diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md new file mode 100644 index 0000000..b84a665 --- /dev/null +++ b/wiki/_Sidebar.md @@ -0,0 +1,24 @@ +**NATO alphabet** + +- [Home](Home) +- [Install](Install) +- [Usage](Usage) +- [Development](Development) + +**Dansk** + +- [Hjem](Home-da) +- [Installation](Install-da) +- [Brug](Usage-da) +- [Udvikling](Development-da) + +**Bahasa Melayu** + +- [Utama](Home-ms) +- [Pemasangan](Install-ms) +- [Penggunaan](Usage-ms) +- [Pembangunan](Development-ms) + +**Links** + +- [Repository](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/026-nato-alphabet)