mdbook_cat_prep/models.rs
1//! modul obsahující jednotlivé objektu cat-prepu
2//!
3//! každý model spočívá v páru karta - profil,
4//! kdy karta odpovídá TOMLu přečtenému z headeru
5//! souboru (nebo ze souboru ucitel.toml)
6
7use std::path::PathBuf;
8use serde::{Serialize, Deserialize};
9
10/// Karta učitele
11///
12/// Tato struktura reprezentuje konfigurační soubor
13/// `teachers/ucitel.toml`, který obsahuje základní
14/// informace o vyučujícím.
15///
16/// Tento soubor je následně využíván k identifikace
17/// autora, zodpovědných osob, vytvoření profilu
18/// učitele a asociaci předmětů a jednotlivých materiálů
19#[derive(Debug, Clone, Serialize, Deserialize)]
20pub struct TeacherCard {
21 /// jméno vyučujícího,
22 /// mělo by být opravdové jméno
23 /// a korespondovat s gitovou
24 /// konfigurační hodnotou `user.name`
25 pub jmeno: String,
26 /// email vyučujícího,
27 /// měl by korespondovat
28 /// s gitovou konfigurační hodnotou
29 /// `user.email`
30 pub email: String,
31 /// uživatelské jméno uživatele,
32 /// nesmí obsahovat mezery,
33 /// využit pro mezistránkové odkazy,
34 /// další kritérium pro vyhledávání
35 /// souborů v repozitáři modifikovaných/vytvořených
36 /// uživatelem
37 pub username: String,
38 /// popisek vyučujícího.
39 /// může obsahovat cokoliv,
40 /// formátováno jako markdown
41 pub bio: String,
42}
43
44/// Karta článku
45///
46/// Tato struktura reprezentuje konfigurační
47/// hodnoty daného článku ve formátu TOML,
48/// odděleno řádkem `+++` od těla článku
49///
50/// využito při generování metadat článku,
51/// a generování odkazů na mnoha jiných místech
52#[derive(Debug, Clone, Serialize, Deserialize)]
53pub struct ArticleCard {
54 /// název článku,
55 /// bude se objevovat v odkazech
56 /// a nahoře v kartě článku
57 pub nazev: String,
58 /// seznam tagů, které má daný článek
59 /// využit pro vytvoření databáze tagů
60 /// a následné nalinkování
61 pub tagy: Vec<String>,
62 /// datum, může obsahovat cokoliv
63 pub datum: Option<String>,
64 /// tato složka je pomocná a nemá být
65 /// konfigurována v markdown souboru,
66 /// jejím účelem je uchovávat cestu k souboru,
67 /// ke kterému karta patří v kontextech,
68 /// kde není použít [`Article`]
69 /// (nebo dokud není sestavena databáze článků)
70 pub _resolved_path: Option<PathBuf>,
71}
72
73/// Článek
74///
75/// Tato struktura reprezentuje všechna
76/// metadata daného materiálu, slouží jako
77/// hlavní zdroj informací.
78#[derive(Debug, Clone, Serialize, Deserialize)]
79pub struct Article {
80 /// karta článku
81 pub card: ArticleCard,
82 /// kdy byl naposled článek modifikován;
83 /// vypočítáno pomocí gitu.
84 pub last_modified: String,
85 /// kým byl článek naposledy modifikován;
86 /// informaca získané z gitu.
87 pub modified_by: String,
88 /// autor daného materiálu,
89 /// informace získaná z gitu,
90 /// viz [`Teacher::files_created`].
91 pub author: String,
92 /// cesta k článku,
93 /// relativní ke složce `src`
94 /// (a tudíž kořenovému adresáři webu)
95 pub path: PathBuf,
96 /// pokud se podle [`Article::modified_by`] podařilo
97 /// najít vyučujícího, bude zde uložena jeho karta
98 pub modified_resolved: Option<TeacherCard>,
99 /// pokud se podle [`Article::author`] podařilo
100 /// najít vyučujícího, bude zde uložena jeho karta
101 pub resolved_author: Option<TeacherCard>,
102 /// zde se nalézá přiřazená karta předmětu,
103 /// typ `Option` je použit proto, protože v době
104 /// parsování není známý předmět, ke kterému článek patří
105 pub subject_card: Option<SubjectCard>,
106}
107
108/// Karta předmětu
109///
110/// Tato struktura obsahuje informace z headeru
111/// předmětu. Je využita pro generování profilu
112/// předmětu a obsahuje základní informace.
113///
114/// Také využita v místech, kde není potřeba,
115/// nebo není dostupný,
116#[derive(Debug, Clone, Serialize, Deserialize)]
117pub struct SubjectCard {
118 /// název předmětu, bude použit ve všech odkazech
119 /// a seznamech.
120 pub nazev: String,
121 /// osoba zodpovědná za daný předmět,
122 /// buď hlavní vyučující, nebo vyučující
123 /// zodpovědný za dokumentaci (v případě více vyučujícíh)
124 pub zodpovedna_osoba: String,
125 /// krátký popisek předmětu
126 pub bio: String,
127 /// cesta k předmětu,
128 /// pro účely, kde je dostupná jenom karta
129 /// předmětu nebo dokud není vytvořený profil
130 /// předmětu
131 pub _resolved_path: Option<PathBuf>,
132}
133
134/// Předmět
135///
136/// Tato struktura reprezentuje celý profil předmětu,
137/// využitý pro sestavování hierarchie knihy,
138/// kategorizace článků a podobně.
139#[derive(Debug, Clone, Serialize, Deserialize)]
140pub struct Subject {
141 /// karta předmětu
142 pub card: SubjectCard,
143 /// cesta k předmětu
144 pub path: PathBuf,
145 /// kořen předmětu,
146 /// všechny `mdbook` kapitoly,
147 /// jejichž cesta má `path_root` jako
148 /// prefix jsou považovány za články
149 /// spadající pod tento předmět
150 pub path_root: PathBuf,
151 /// články spadající pod tento předmět
152 pub articles: Vec<Article>,
153 /// pokud se podařilo vyřešit identitu
154 /// zodpovědné osoby, zde je uložena
155 /// její karta
156 pub resolved_author: Option<TeacherCard>,
157}
158
159/// Učitel
160///
161/// Tato struktura obsahuje kompletní profil učitele.
162/// Jedná se o stěžejní strukturu pro generování výstupu.
163#[derive(Debug, Clone, Serialize, Deserialize)]
164pub struct Teacher {
165 /// karta učitele
166 pub card: TeacherCard,
167 /// předměty, na kterých se
168 /// vyučující podílel
169 pub subjects: Vec<Subject>,
170 /// články, které vyučující založil
171 pub articles: Vec<Article>,
172 /// seznam souborů, které uživatel přidal
173 /// do gitu a stále existují
174 pub files_created: Vec<PathBuf>,
175}