#68 Documentation restructure

README.md

@@ -1,51 +1,52 @@
 # Kipa
 
-Kipa-ohjelmisto, jota käytetään partiotaitokilpailujen tuloslaskentaan. 
+Kipa eli Kisapalvelu on partiotaitokilpailujen tuloslaskentaan tehty
+selainpohjainen ohjelmisto. Kipalla voi laskea myös tehtävät joihin Tupa,
+Excel tai taskulaskin ei taivu. Kipa soveltuu myös sinulle, joka tarvitset
+vaihtelevia interpolointikertoimia, syötät tuloksia muillakin kuin
+Windows-koneilla, tai haluat helpottaa tarkistuslaskentaa.
 
-Asennusohjeet löytyvät [wikistä](https://github.com/partio-scout/kipa/wiki).
+Kipaa saa käyttää, kehittää ja levittää vapaasti. Kipaa jaellaan GNU GPLv3
+-lisenssin ehtojen mukaisesti. Lue lisää tiedostosta
+[COPYING](COPYING).
 
-## Lisenssi
+Ohjeita Kipan käyttöön ja tarkempaa tietoa ohjelmistosta löytyy
+[käyttöohjeesta](docs/manual.md).
 
-Tämä ohjelma on vapaa; tätä ohjelmaa on sallittu levittää edelleen ja muuttaa GNU yleisen lisenssin (GPL-lisenssin) ehtojen mukaan sellaisina kuin Free Software Foundation on ne julkaissut Lisenssin version 3 mukaisesti.
+Asennusohjeet löytyvät [asennusohjeesta](docs/installation.md).
 
-Tätä ohjelmaa levitetään siinä toivossa, että se olisi hyödyllinen, mutta ilman mitään takuuta; ilman edes hiljaista takuuta kaupallisesti hyväksyttävästä laadusta tai soveltuvuudesta tiettyyn tarkoitukseen. Katso GPL-lisenssistä lisää yksityiskohtia.
+## Kehitys
 
-Tämän ohjelman mukana pitäisi tulla kopio GPL-lisenssistä; jos näin ei ole, kirjoita osoitteeseen Free Software Foundation Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+Apu Kipan kehittämiseen on tervetullutta. Lisätietoa kehitysprosessista ja
+siihen osallistumisesta löytyy
+[prosessiohjeesta](docs/CONTRIBUTING.md). Yleistä tietoa kehittämisestä
+löytyy [kehittäjäohjeesta](docs/development.md).
 
+## Tekijänoikeudet
 
-## Kehittäminen
+Tämän ohjelmiston tekijänoikeudet kuuluvat ainakin vuosilta 2008 - 2012
+Espoon Partiotuki ry.:lle ([email protected]) ja sen jälkeen muille Kipan
+kehitykseen osallistuneille henkilöille.
 
-### Paikallisen kehitysympäristön pystytys
+Alkuperäiseen projektiryhmään ovat kuuluneet:
 
+* Joonas "Jones" Hirn
+* Visa "Viski" Jokelainen
+* Frans "Ransu" Korhonen
+* Samu Wikstedt
+* Markus "Mara" Vuorinen
 
-* Luo Kipalle virtuaaliympäristö jonnekkin: `python -m venv /tmp/venv`
-* Ota virtuaaliympäristö käyttöön: `source /tmp/venv/bin/activate`
-* Asenna riippuvuudet: `pip install -r requirements.txt`
-* Luo jonnekkin väliaikainen hakemisto tietokannalle: `mkdir /tmp/tietokanta`
-* Kopioi kehitystietokanta: `cp docs/initial.db /tmp/tietokanta/kipa.db`
-* `cp ./web/settings/local.py.example ./web/settings/local.py`
-* Muokkaa edellisessä luotuun asetustiedostoon tietokantatiedostolle polku `/tmp/tietokanta/kipa.db`
-* `cd web`
-* `python manage.py migrate --fake-initial --noinput`
-* `python manage.py runserver`
+Muuta projektiryhmää, joka on ollut enemmän tai vähemmän projektin
+vaiheissa mukana: Janne "Peltsi" Peltola, Teemu Penttilä, Martti "Mara"
+Suontausta.
 
-### Yksikkötestien ajaminen
+Kipaa on ollut jatkokehittämässä tekijöitä alkuperäisen projektiryhmän
+ulkopuolelta.
 
-* `cd web`
-* `python manage.py test`
+## Kehitysprojekti
 
-### E2E-testien ajaminen
-
-* Käynnistä Kipan kehityspalvelin
-* `python3 -m venv ./robot-venv`
-* `source ./robot-venv/bin/activate`
-* `pip install robotframework robotframework-seleniumlibrary`
-* `robot --outputdir /tmp/test-report --variable BROWSER:headlessfirefox --exitonfailure ./web/robot/perustoiminnot.robot`
-
-Hakemistosta `./web/roobt` löytyy myös toinen robot-tiedosto nimeltään
-`autentikointi.txt`, mutta sen ajaminen ei taida onnistua, ellei ensin toteuta
-Kipaan suunniteltua kirjautumista.
-
-### Python-koodin formatointi
-
-Koodi noudattaa Black-autoformatterin vesion 24.10.0 mukaista tyyliä. Blackille annetaan lippu `--target-version py312`. Formatointi tarkastetaan osana CI-putkea.
+Kipa on alunperin kehitetty espoolaisten partiolaisten voimin korvaamaan
+Sakari "Sacu" Koutin koodaama Tupa ja vastaamaan ajan haasteisiin.
+Kehitystyö alkoi lokakuussa 2008 ja ensimmäinen valmis versio valmistui
+Keväällä 2011. Espoon Partiotuki ry. oli taustayhteisönä ja tuki
+taloudellisesti projektia sen kehitysaikana.

docs/development.md

@@ -0,0 +1,126 @@
+# Kehittäjäohje
+
+## Arkkitehtuuri
+
+Kisapalvelu, Kipa, on puhdas web-applikaatio. Laskenta on toteutettu
+Pythonilla. Web näkymät on rakennettu Django-ohjelmistokehyksen päälle,
+joka on toteuttu pythonilla. Kaikki syötteet tallennetaan sqlite-kantaan,
+jonka yhteydet hoitaa Django. SQLite-toiminnalisuus tulee Pythonin mukana.
+Web-palvelimena on käytetty Apachea sekä djangon kehitysserveriä, mutta ei
+pitäisi olla esteitä toteuttaa toiminnallisuutta millä tahansa
+web-palvelimella joka tukee Pythonin suorittamista. Django tukee myös
+MySQL- sekä PostegreSQL-kantoja, pienellä muutoksella settings.py
+tiedostoon. Mikäli haluat rakentaa julkisen verkkopalvelun jossa voluumi
+voi olla kovempi kannattaa tämä pitää mielessä.
+
+## Suorituskyky ja skaalautuvuus
+
+Normaalikäytössä ei Kipa nosta mainittavasti koneen CPU-kuormaa. Yhdellä
+kannettavalla voidaan hyvin ajaa kisatoimiston palveluja. Piikkittäisiä
+kuormituksia syntyy ainoastaan tulosten laskemisesta, isohkoissa
+kilpailussa, jossa on tuhansia syötteitä, vie kaavojen parsiminen ja
+laskenta isoille sarjoille joissain tapauksissa joitain sekunteja. Testien
+mukaan kuorma kuitenkin säikeistyy käytössä olevien threadien määrän
+mukaan - kuitenkin vain yksi per istunto.
+
+Alkuperäisessä Kehitysvaiheessa on testejä ajettu pitkään (muinaisella)
+850Mhz Pentiumilla jossa 128Mt muistia - tälläiselläkään koneella ei
+suorituskykyongelmia tule muuta kuin hetkellisesti laskennassa.
+
+Testimielessä Kipan kantaan on ajettu yhtäaikaa parikymmentä kilpailua
+kokonaisuudessaan, jolloin syötteiden määrä on noussut tuhansiin, tällä ei
+kuitenkaan ole nähty olevan vaikutusta suorituskykyyn.
+
+## Paikallisen kehitysympäristön pystytys
+
+* Luo Kipalle virtuaaliympäristö jonnekkin: `python -m venv /tmp/venv`
+* Ota virtuaaliympäristö käyttöön: `source /tmp/venv/bin/activate`
+* Asenna riippuvuudet: `pip install -r requirements.txt`
+* Luo jonnekkin väliaikainen hakemisto tietokannalle: `mkdir /tmp/tietokanta`
+* Kopioi kehitystietokanta: `cp docs/initial.db /tmp/tietokanta/kipa.db`
+* `cp ./web/settings/local.py.example ./web/settings/local.py`
+* Muokkaa edellisessä luotuun asetustiedostoon tietokantatiedostolle polku
+  `/tmp/tietokanta/kipa.db`
+* `cd web`
+* `python manage.py migrate --fake-initial --noinput`
+* `python manage.py runserver`
+
+## Yksikkötestien ajaminen
+
+* `cd web`
+* `python manage.py test`
+
+Kipaa voi myös käyttää testipalvelimen kanssa, joka on muuten samanlainen
+kuin runserver, paitsi että se käyttää virtuaalista tietokantaa muistissa.
+Ei tee mitään muutoksia tiedostoihin. Turvallinen erilaisiin kokeiluihin.
+Voidaan täyttää halutulla tietokantapohjalla (fixture). esim.
+
+```
+python manage.py testserver fixtures/tests/katuu.xml
+```
+
+## Päästä päähän -testien ajaminen
+
+* Käynnistä Kipan kehityspalvelin
+* `python -m venv ./robot-venv`
+* `source ./robot-venv/bin/activate`
+* `pip install robotframework robotframework-seleniumlibrary`
+* `robot --outputdir /tmp/test-report --variable BROWSER:headlessfirefox \
+  --exitonfailure ./web/robot/perustoiminnot.robot`
+
+Hakemistosta `./web/roobt` löytyy myös toinen robot-tiedosto nimeltään
+`autentikointi.txt`, mutta sen ajaminen ei taida onnistua, ellei ensin
+toteuta Kipaan suunniteltua kirjautumista.
+
+## Python-koodin formatointi
+
+Koodi noudattaa Black-autoformatterin vesion 24.10.0 mukaista tyyliä.
+Blackille annetaan lippu `--target-version py312`. Formatointi tarkastetaan
+osana CI-putkea.
+
+## Selityksiä lähdekooditiedostoista
+
+* `web/tupa/`
+  - `admin.py`
+    * Djangon luoman admin sivun määritely.
+  - `AritmeettinenLaskin.py`
+    * Laskin joka laskee matemaattisia lauekeita merkkijonosta jossa on
+      merkejä +-/\*() sekä numeroita.
+  - `duplicate.py`
+    * Tiedon monistaminen. Tehtävien kopiointi, XML-tietokantatiedoston
+      luonti.
+  - `formit.py`
+    * Perus formien määritys. Formeja käytetään näkymissä (views.py)
+  - `logger.py`
+    * Kirjaus, ja nauhoitus. Kirjaa laskimen välivaiheita. Nauhoittaa post
+      dataa.
+  - `models.py`
+    * Django datamalli. Koko systeemin ydin.
+    * Datamalliin pohjatuu sekä tietokanta että näkymät.
+    * Myös laskin käyttää datamallia tiedon haussa.
+  - `TehatavanMaaritys.py`
+    * Tehtävän määrityksen formit.
+  - `tests.py`
+    * Yksikkötestit, Testaa järjestelmää erilaisilla testeillä.
+      - Aritmeettisen laskimen perustoimitukset.
+      - Sarjakohtaisten tulosten testaus.
+      - Kaikkien näkymien avautuminen testidatalla.
+      - Tiedon tallentuminen näkymillä.
+  - `Tuloslaskin.py`
+    * Laskee tulokset tietokannan tietojen pohjalta.
+  - `urls.py`
+    * Näkymien hakemistopolut.
+  - `views.py`
+    * Näkymät, jokaisen sivun aivot.
+* `web/tupa/templates/`
+  - `404.html`
+  - `500.html`
+  - `base.html`
+* `web/tupa/templates/tupa/`
+  - Näkymien templaatit
+* `web/tupa/templates/tupa/forms/`
+  - lomakekohtaiset templaatit
+* `web/media/`
+  - kuvat
+  - css
+  - yms. tiedostot

docs/installation.md

@@ -0,0 +1,110 @@
+# Asennusohjeet
+
+## Kipan verkkoasennus
+
+### Lähiverkko
+
+Kaikkien tietokoneiden pitää olla samassa verkossa niin että niillä on
+verkkoyhteys palvelimelle johon Kipa on asennettu. Yhteyden toimivuutta voi
+kokeilla vaikka ping \<IP osoite\> komennolla. Palvelimelle tarvitaan
+portti 80 auki http-liikennöintiä varten. Jos kisatoimistosta ei ole pääsy
+Internettiin kannattaa harkita palomuurin sammuttamisesta palvelimelta.
+
+### Internet
+
+On myös mahdollista asentaa Kipa julkisesti Internettiin jolloin kaikki
+kisat ovat verkossa näkyvillä kaikille, tällöin kannattaa miettiä onko
+turvallisuusriskinä, että kuka tahansa, jolla on osoite, voi mennä
+muokkamaan kisan määrittelyitä ja tehtäviä. Lisäturvana kannattaa harkita
+käyttäjäautentikoitia osoitteeseen jossa Kipa pyörii. Samoin rajoituksia
+voi tulla syrjäseuduilla toimiville kisatoimistoille, joihin ei saada
+riittävän hyvää verkkoyhteyttä.
+
+## Docker-asennus
+
+1. Luo itsellesi GitHubin personal access
+   token [täältä](https://github.com/settings/tokens) jakirjaudu
+   Docker-clientillä sisään GitHubin pakettivarantoon esimerkiksi
+   komennolla `docker login ghcr.io`
+2. Aja komento `docker run -d -p 3000:3000 -v kipa_db:/app/db --name kipa -d ghcr.io/partio-scout/kipa:latest`
+    * Halutessasi voit myös käyttää kehitysversiota vaihtamalla `latest`-tagin sijaan `develop`in.
+3. Mene selaimella osoitteeseen http://localhost:3000/kipa/ – voilá!
+
+Yllä opastettu ajotapa käyttää kipa_db-nimisessä Docker-volumessa olevaa
+SQLite-kantaa. Sen sijaan voit käyttää esimerkiksi MySQL-kantaa
+mounttaamalla erillisen local.py-tiedoston tähän tapaan:
+`-v /home/user/kipa/local.py:/app/web/settings/local.py`. Voit myös yliajaa
+muita settings/__init__.py:ssä olevia määrityksiä em. tavalla, esimerkiksi
+ottaa käyttöön välimuistituksen.
+
+## macOS-asennus
+
+Toimivaksi todettu macOS Montereylla (12.0), luultavasti toimii myös
+uudemmilla käyttöjärjestelmillä. Huom! Tämä ohje asentaa Kipan
+kehityspalvelimen (development server).
+
+macOS sisältää valmiiksi kaiken muun, paitsi itse Djangon. Sen asennus on
+hyvin yksinkertainen ja onnistuu keneltä tahansa pääkäyttäjän oikeuksilla.
+
+1. Avaa Terminal klikkaamalla oikeasta yläkulmasta suurennuslasia ja
+   kirjoittamalla hakukenttään Terminal
+2. Asenna Django kirjoittamalla terminaaliin
+   `sudo easy_install django==1.3.1`  
+   Anna salasanasi, jos terminaali sitä kysyy. Tämä asentaa Djangon
+   uusimman saatavilla olevan version.
+3. Hae Kipa GitHubista kirjoittamalla  
+   `git clone https://github.com/partio-scout/kipa.git`  
+   Jos et ole aiemmin käyttänyt Gittiä, tulee näytölle varmistus Command
+   Line Developer Toolsin asentamisesta. Hyväksy asennus ja aja käsky
+   uudelleen.
+4. Hyväksy terminaalin mahdollinen kysymys palvelimen sertifikaatista.
+5. Siirry Kipan web-hakemistoon kirjoittamalla `cd kipa/web`
+6. Käynnistä Django ja Kipa `sudo python manage.py runserver`
+7. Jos saat ilmoitukseksi “Development server is running at...”, voit avata
+   selaimen (esim. Safari) ja kirjoittaa osoitteeksi 127.0.0.1:8000/kipa/
+
+Kun lopetat Kipan käytön, siirry terminaaliin ja paina Ctrl+C, joka
+pysäyttää Djangon.
+
+## Linux-asennus
+
+Pohjalle tarvitaan moderni Linux-käyttöjärjestelmä, testattu Ubuntu
+20.04:lla
+
+Huom! Ohjeessa {{kipa_asennus}} viittaa kansioon, johon Kipa on asennettu
+(eli 2. Kohdassa .zip tiedosto purettu).
+
+1. Lataa Kipa
+   lähdekoodi [GitHubista](https://github.com/partio-scout/kipa/archive/refs/heads/master.zip)
+2. Pura .zip tiedosto kansioon, johon haluat asentaa Kipa
+3. Asenna tarvittavat paketit komennolla
+   `sudo apt install apache2 python libapache2-mod-python mysql-server libmysqlclient-dev python-dev build-essential`
+
+* Pythonin asennuksen jälkeen asenna pip, katso esim.
+  ohjeet: https://stackoverflow.com/a/66719099
+* Pip:n asennuksen jälkeen asenna vaadittava versio Djangosta ajamalla
+  kipa-kansiossa komento pip install -r requirements.txt
+
+4. Lisää /etc/apache2/apache2.conf tiedoston loppuun seuraavat rivit
+
+        <Location "/kipa/">
+          SetHandler python-program
+          PythonHandler django.core.handlers.modpython
+          SetEnv DJANGO_SETTINGS_MODULE web.settings
+          PythonDebug On
+          PythonPath "['{{kipa_asennus}}/kipa', '{{kipa_asennus}}/kipa/web'] + sys.path"
+        </Location>
+
+5. Aja seuraavat komennot
+
+        chown www-data {{kipa_asennus}}/kipa/web
+        chown www-data {{kipa_asennus}}/kipa/web/tupa.db
+        ln -s {{kipa_asennus}}/kipa/web/media /var/www/html/kipamedia
+
+6. Käynnistä apache2 uudestaan komennolla `sudo systemctl restart apache2`
+7. Kipa pitäisi toimia nyt osoitteessa localhost://kipa/
+
+## Windows-asennus
+
+Lataa [asennustiedosto](https://github.com/partio-scout/kipa/releases/tag/1.6.2)
+ja aja se. Testattu toimivaksi Windows 10 ja Windows XP.