From 632fa61b89bc5dd4a658673e649f565973bbb846 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Tue, 13 Oct 2026 15:43:56 +0800 Subject: [PATCH] Move the wiki sources to wiki/ and tidy version history statuses No issue closed: all issues of MIL-001 to MIL-004 are closed. --- README.md | 283 +++++++++++++------------- docs/dictionary.md | 2 +- docs/project-plan.md | 4 +- {docs/wiki => wiki}/Description.da.md | 0 {docs/wiki => wiki}/Description.md | 0 {docs/wiki => wiki}/Description.ms.md | 0 {docs/wiki => wiki}/Home.da.md | 0 {docs/wiki => wiki}/Home.md | 0 {docs/wiki => wiki}/Home.ms.md | 0 {docs/wiki => wiki}/Install.da.md | 0 {docs/wiki => wiki}/Install.md | 0 {docs/wiki => wiki}/Install.ms.md | 0 {docs/wiki => wiki}/Usage.da.md | 0 {docs/wiki => wiki}/Usage.md | 0 {docs/wiki => wiki}/Usage.ms.md | 0 {docs/wiki => wiki}/_Sidebar.md | 2 +- 16 files changed, 146 insertions(+), 145 deletions(-) rename {docs/wiki => wiki}/Description.da.md (100%) rename {docs/wiki => wiki}/Description.md (100%) rename {docs/wiki => wiki}/Description.ms.md (100%) rename {docs/wiki => wiki}/Home.da.md (100%) rename {docs/wiki => wiki}/Home.md (100%) rename {docs/wiki => wiki}/Home.ms.md (100%) rename {docs/wiki => wiki}/Install.da.md (100%) rename {docs/wiki => wiki}/Install.md (100%) rename {docs/wiki => wiki}/Install.ms.md (100%) rename {docs/wiki => wiki}/Usage.da.md (100%) rename {docs/wiki => wiki}/Usage.md (100%) rename {docs/wiki => wiki}/Usage.ms.md (100%) rename {docs/wiki => wiki}/_Sidebar.md (80%) diff --git a/README.md b/README.md index 8784814..8f8f260 100644 --- a/README.md +++ b/README.md @@ -1,141 +1,142 @@ -# Squirrel Census - -Day 25 of Udemy's *100 Days of Code: The Complete Python Pro Bootcamp*: count the -squirrels of the 2018 Central Park Squirrel Census by primary fur colour (gray, -cinnamon, black) and export the counts to `squirrel_count.csv`. Python 3.13 or -later, no runtime dependencies, with tests and source documentation. - -![Program run][img-run] - -## Requirements - -- Python 3.13 or later (`python --version` on Windows, `python3 --version` on Linux and macOS). -- `venv`, which ships with Python (on Debian: the `python3-venv` package). -- The 2018 census file. It is already in the repository under `data/`. -- Optional: [Doxygen][doxygen] 1.9 or later, only to build the source documentation. - -There are no runtime dependencies: the program uses only the Python standard library -([ADR-0001][adr-0001]). `pytest` is needed only to run the tests. - -## Set up - -Create a local virtual environment named `.venv` in the project folder, upgrade `pip` -and install the project with its development tools (pytest, ruff, mypy). - -### Windows powershell - -```powershell -python -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 the current session: -`Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned`. - -### Linux debian - -```bash -sudo apt install python3 python3-venv -python3 -m venv .venv -source .venv/bin/activate -python -m pip install --upgrade pip -python -m pip install -e ".[dev]" -``` - -### MacOS - -```bash -python3 -m venv .venv -source .venv/bin/activate -python -m pip install --upgrade pip -python -m pip install -e ".[dev]" -``` - -On macOS, Python 3.13 can be installed with `brew install python@3.13`. - -## Run - -With the virtual environment active, run from the project folder: - -```bash -python -m squirrel -``` - -The program reads `data/2018_Central_Park_Squirrel_Census_-_Squirrel_Data.csv`, prints -the colour counts and writes `squirrel_count.csv`: - -```text -Gray: 2473 -Cinnamon: 392 -Black: 103 -``` - -Use other files by passing them as arguments, `python -m squirrel `. -If the census file does not exist the program prints a message and exits with status 2. - -## Run the tests - -```bash -python -m pytest -``` - -![Test run][img-tests] - -The tests use small fixture rows; one test also checks the real 2018 census file when -it is present. - -## Continuous integration - -The workflow [`.gitea/workflows/ci.yml`][ci] runs for every push to `main` and for every -pull request. It sets up Python 3.13, creates a `.venv`, upgrades `pip`, installs the -project with `.[dev]` and runs `python -m pytest`. It uses `github.*` contexts only, so -it also runs on GitHub Actions. - -## Build the source documentation - -The source is documented with Doxygen comments and configured by [`Doxyfile`][doxyfile]. - -```bash -doxygen Doxyfile -``` - -Open `docs/doxygen/html/index.html` in a browser. The output folder is ignored by git. - -## Project layout - -```text -.gitea/workflows/ci.yml continuous integration workflow -data/ the 2018 census file -docs/ business case, plan, milestones, models, reviews, ADRs -docs/images/ screenshots used by this README and the wiki -src/squirrel/ the package: census.py, cli.py, constants.py -tests/ pytest tests -Doxyfile Doxygen configuration -pyproject.toml project configuration (Python >=3.13, no runtime dependencies) -squirrel_count.csv the result of the assignment -``` - -The project documents, in reading order: [Business Case][bc], [Stakeholder -Analysis][sa], [Project Plan][pp], [Use Case][uc], [Domain Model][dm], [ADR-0001][adr-0001]. -The repository also has a wiki in English, Danish and Bahasa Malaysia. - -## License - -GNU Affero General Public License v3.0 or later. See [LICENSE][license]. - ---- - -[img-run]: docs/images/run.png -[img-tests]: docs/images/tests.png -[doxygen]: https://www.doxygen.nl/ -[adr-0001]: docs/adr/adr-0001-standard-library-instead-of-pandas.md -[ci]: .gitea/workflows/ci.yml -[doxyfile]: Doxyfile -[bc]: docs/business-case.md -[sa]: docs/stakeholder-analysis.md -[pp]: docs/project-plan.md -[uc]: docs/uc-001/uc.md -[dm]: docs/domain-model.md -[license]: LICENSE +# Squirrel Census + +Day 25 of Udemy's *100 Days of Code: The Complete Python Pro Bootcamp*: count the +squirrels of the 2018 Central Park Squirrel Census by primary fur colour (gray, +cinnamon, black) and export the counts to `squirrel_count.csv`. Python 3.13 or +later, no runtime dependencies, with tests and source documentation. + +![Program run][img-run] + +## Requirements + +- Python 3.13 or later (`python --version` on Windows, `python3 --version` on Linux and macOS). +- `venv`, which ships with Python (on Debian: the `python3-venv` package). +- The 2018 census file. It is already in the repository under `data/`. +- Optional: [Doxygen][doxygen] 1.9 or later, only to build the source documentation. + +There are no runtime dependencies: the program uses only the Python standard library +([ADR-0001][adr-0001]). `pytest` is needed only to run the tests. + +## Set up + +Create a local virtual environment named `.venv` in the project folder, upgrade `pip` +and install the project with its development tools (pytest, ruff, mypy). + +### Windows powershell + +```powershell +python -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 the current session: +`Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned`. + +### Linux debian + +```bash +sudo apt install python3 python3-venv +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +### MacOS + +```bash +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +On macOS, Python 3.13 can be installed with `brew install python@3.13`. + +## Run + +With the virtual environment active, run from the project folder: + +```bash +python -m squirrel +``` + +The program reads `data/2018_Central_Park_Squirrel_Census_-_Squirrel_Data.csv`, prints +the colour counts and writes `squirrel_count.csv`: + +```text +Gray: 2473 +Cinnamon: 392 +Black: 103 +``` + +Use other files by passing them as arguments, `python -m squirrel `. +If the census file does not exist the program prints a message and exits with status 2. + +## Run the tests + +```bash +python -m pytest +``` + +![Test run][img-tests] + +The tests use small fixture rows; one test also checks the real 2018 census file when +it is present. + +## Continuous integration + +The workflow [`.gitea/workflows/ci.yml`][ci] runs for every push to `main` and for every +pull request. It sets up Python 3.13, creates a `.venv`, upgrades `pip`, installs the +project with `.[dev]` and runs `python -m pytest`. It uses `github.*` contexts only, so +it also runs on GitHub Actions. + +## Build the source documentation + +The source is documented with Doxygen comments and configured by [`Doxyfile`][doxyfile]. + +```bash +doxygen Doxyfile +``` + +Open `docs/doxygen/html/index.html` in a browser. The output folder is ignored by git. + +## Project layout + +```text +.gitea/workflows/ci.yml continuous integration workflow +data/ the 2018 census file +docs/ business case, plan, milestones, models, reviews, ADRs +docs/images/ screenshots used by this README and the wiki +src/squirrel/ the package: census.py, cli.py, constants.py +tests/ pytest tests +wiki/ wiki pages in English, Danish (.da) and Bahasa Malaysia (.ms) +Doxyfile Doxygen configuration +pyproject.toml project configuration (Python >=3.13, no runtime dependencies) +squirrel_count.csv the result of the assignment +``` + +The project documents, in reading order: [Business Case][bc], [Stakeholder +Analysis][sa], [Project Plan][pp], [Use Case][uc], [Domain Model][dm], [ADR-0001][adr-0001]. +The repository also has a wiki in English, Danish and Bahasa Malaysia. + +## License + +GNU Affero General Public License v3.0 or later. See [LICENSE][license]. + +--- + +[img-run]: docs/images/run.png +[img-tests]: docs/images/tests.png +[doxygen]: https://www.doxygen.nl/ +[adr-0001]: docs/adr/adr-0001-standard-library-instead-of-pandas.md +[ci]: .gitea/workflows/ci.yml +[doxyfile]: Doxyfile +[bc]: docs/business-case.md +[sa]: docs/stakeholder-analysis.md +[pp]: docs/project-plan.md +[uc]: docs/uc-001/uc.md +[dm]: docs/domain-model.md +[license]: LICENSE diff --git a/docs/dictionary.md b/docs/dictionary.md index ec5bcaf..497457b 100644 --- a/docs/dictionary.md +++ b/docs/dictionary.md @@ -11,7 +11,7 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-13 | Proposed | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f1b3c03] | +| 2026-10-13 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f1b3c03] | | 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | CrossReference: added [DM-002] | [259d017] | --- diff --git a/docs/project-plan.md b/docs/project-plan.md index 5f36040..99ffe01 100644 --- a/docs/project-plan.md +++ b/docs/project-plan.md @@ -11,8 +11,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [f1b3c03] | -| 2026-10-13 | Proposed | Jens Tirsvad Nielsen | AI as stand-in for S01 | CrossReference: added [US-001] | [259d017] | +| 2026-10-13 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [f1b3c03] | +| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | CrossReference: added [US-001] | [259d017] | --- ## Purpose diff --git a/docs/wiki/Description.da.md b/wiki/Description.da.md similarity index 100% rename from docs/wiki/Description.da.md rename to wiki/Description.da.md diff --git a/docs/wiki/Description.md b/wiki/Description.md similarity index 100% rename from docs/wiki/Description.md rename to wiki/Description.md diff --git a/docs/wiki/Description.ms.md b/wiki/Description.ms.md similarity index 100% rename from docs/wiki/Description.ms.md rename to wiki/Description.ms.md diff --git a/docs/wiki/Home.da.md b/wiki/Home.da.md similarity index 100% rename from docs/wiki/Home.da.md rename to wiki/Home.da.md diff --git a/docs/wiki/Home.md b/wiki/Home.md similarity index 100% rename from docs/wiki/Home.md rename to wiki/Home.md diff --git a/docs/wiki/Home.ms.md b/wiki/Home.ms.md similarity index 100% rename from docs/wiki/Home.ms.md rename to wiki/Home.ms.md diff --git a/docs/wiki/Install.da.md b/wiki/Install.da.md similarity index 100% rename from docs/wiki/Install.da.md rename to wiki/Install.da.md diff --git a/docs/wiki/Install.md b/wiki/Install.md similarity index 100% rename from docs/wiki/Install.md rename to wiki/Install.md diff --git a/docs/wiki/Install.ms.md b/wiki/Install.ms.md similarity index 100% rename from docs/wiki/Install.ms.md rename to wiki/Install.ms.md diff --git a/docs/wiki/Usage.da.md b/wiki/Usage.da.md similarity index 100% rename from docs/wiki/Usage.da.md rename to wiki/Usage.da.md diff --git a/docs/wiki/Usage.md b/wiki/Usage.md similarity index 100% rename from docs/wiki/Usage.md rename to wiki/Usage.md diff --git a/docs/wiki/Usage.ms.md b/wiki/Usage.ms.md similarity index 100% rename from docs/wiki/Usage.ms.md rename to wiki/Usage.ms.md diff --git a/docs/wiki/_Sidebar.md b/wiki/_Sidebar.md similarity index 80% rename from docs/wiki/_Sidebar.md rename to wiki/_Sidebar.md index a0ee5ea..bb3fffb 100644 --- a/docs/wiki/_Sidebar.md +++ b/wiki/_Sidebar.md @@ -1,4 +1,4 @@ - + **Squirrel Census** -- 2.54.0