Update README.md with project description and goals

README.md

@@ -13,7 +13,88 @@ It generates a static web page with a list of all our projects based on the GitH
 ## ProjectIndexer options
 - `fetch-github` - fetches data from GitHub API and saves it to `data/repos.json`
 - `generate` - generates static web page from `data/repos.json` and saves it to `output` folder
-  - `--compile-tailwind` - compiles tailwind css 
+  - `--compile-tailwind` - compiles tailwind css
 - `serve` - serves the static web page from `output` folder
 
 More predefined commands in `Makefile`.
+
+# Indexace projektů pro RoboticsBrno (CZ)
+
+Tento projekt slouží k automatickému generování portfolia projektů naší organizace na GitHubu.
+ProjektIndexer je statický web generátor napsaný v Pythonu a měl by se automaticky spouštět v nastavených intervalech pomocí GitHub Actions.
+
+## Cíl
+Cílem projektu je udržovat aktuální seznam, popis a informace o projektech bez nutnosti ruční údržby.
+Ukázat veřejnosti (i členům) naši práci v přehledné a jednoduché formě na webu.
+Projekty se budou seskupovat podle kategorií a bude možné je filtrovat například podle projektů.
+Každý projekt bude mít svoji podstránku s relevantními informacemi a odkazy na repozitáře.
+Část funkcionality se bude zpracovávat z informací (tagů, popisu) z GitHubu a druhou část bude muset uživatel vyplnit ručně (např. obrázky, popis - asi YAML).
+
+## Fungování
+
+## Data z GitHubu
+Data o projektech se získávají z GitHub API. Pro získání dat je potřeba mít GitHub token, který se uloží do souboru `.env` do proměnné `MY_GITHUB_TOKEN`.
+
+Zpracovávaná data
+- `name` - název projektu
+- `description` - popis projektu
+- `html_url` - odkaz na GitHub repozitář
+- `homepage` - odkaz na web projektu
+- `topics` - tagy projektu
+  - jelikož se dají tagy jednoduše nastavovat, můžeme je použít pro kategorizaci projektů (např. `robotka`, `rbcx`, `smd-challenge`, `hardware`, ...)
+  - také by šlo taky využit na skrývýní / zobrazení projektů na webu (např. `hidden`). Nebo naopak zveřejnění hlavičky privátního repozitáře (např. `private-publish-header`) - pro kompletní prolinkování našich repozitářů.
+- `language` - programovací jazyk projektu
+- `created_at` - datum vytvoření projektu
+  - lze využít pro řazení projektů
+- `updated_at` - datum poslední aktualizace projektu
+  - lze využít pro řazení projektů
+  - na úvodní stránce můžeme informovat o změnách v projektech
+- `license` - licence projektu
+- `contributors` - seznam přispěvatelů
+  - do budoucna propojit s https://team.robotikabrno.cz/ (lépe sjednotit)
+- `readme` - obsah README.md
+  - zobrazit na podstránce projektu (správně zpracovat obrázky, odkazy, ...)
+- `images` - obrázky projektu
+  - aktuálně nejspíš nepoužíváme (možná do budoucna)
+- `stars` - počet hvězdiček
+  - lze využít pro řazení projektů
+- `issues` - počet issues
+
+### README a popis projektu
+Každý repozitář by měl mít ideálně nastaven Popis projektu na GH a ideálně by měl obsahovat i README.md soubor (CZ/EN - lépe EN).
+Pokud nebude README.md soubor, tak se zobrazí pouze popis projektu z GH.
+Popis projektu by mohl ideálně začínat Emoji (např. 🤖 ) a následně krátkým popisem projektu.
+
+### Obrázky projektu
+Obrázky projektu by měly být v adresáři `images` případně `img` v kořenovém adresáři repozitáře.
+Na webu se budou řadit podle názvů z repa.
+Akceptované soubory: `.png`, `.jpg`, `.jpeg`, (`.svg` spíše ne).
+
+## Doplnění dat
+Některá data se nedají získat z GitHubu a je potřeba je doplnit ručně.
+
+### Kategorie
+Aby bylo možné projekty seskupovat do kategorií, je potřeba každý projekt označit tagem v GitHubu.
+Při generování se bude hledat složka `projects` a v ní soubor s názvem tagu (např. `robotka.md`).
+Readme bude začínat YAML hlavičkou s informacemi o projektu.
+```yaml
+name: Robotka
+name_cz: Robotka
+description: Robotka is a small robot for educational purposes.
+description_cz: Robotka je malý robot pro vzdělávací účely.
+repository:
+  - name: robotka library
+    url: https://github.com/RoboticsBrno/RB3204-RBCX-Robotka-library
+  - name: robotka-examples
+    url: https://github.com/RoboticsBrno/robotka-examples
+web: https://robotka.robotickytabor.cz/
+authors:
+  - name: Jan Novák (dohledá si další údaje samo)
+...
+---
+Markdown text...
+
+```
+
+### Obrázky
+Cesta k obrázkům začíná `R:<repo name>/images/...` (např. `R:robotka/images/...`)

requirements.txt

@@ -8,4 +8,5 @@ livereload
 python-dotenv~=1.0.0
 pytest
 PyYAML~=6.0
-Markdown~=3.3.7
+Markdown~=3.3.7
+click