docs: Some docs modifications

2026-02-11 22:29:05 +01:00
parent c37a114a78
commit 5ac84e3690
7 changed files with 289 additions and 8 deletions
--- a/web/content/posts/api/lib/index.md
+++ b/web/content/posts/api/lib/index.md
@@ -1,6 +1,6 @@
 ---
 title: "Oficiální knihovna"
-date: 2025-12-20
+date: 2026-02-11
 tags: ["api", "docs"]
 hiddenInHomelist: true
 TocOpen: true
--- a/web/content/posts/api/usage/index.md
+++ b/web/content/posts/api/usage/index.md
@@ -30,16 +30,22 @@ Ačkoliv v současnosti vrací stejná data jako `/versioned/v1`, jeho podpora m

 API je verzované, aby byla zajištěna zpětná kompatibilita. Zde je seznam dostupných verzí:

+- ### [Verze 3 (v2)](../v3)
+  **Status:** Stabilní
+  **Endpoint:** `/versioned/v3`
+  
+  Toto je aktuální a doporučená verze API. Obsahuje velké změny oproti V2 a obsahuje nové data. 
+
 - ### [Verze 2 (v2)](../v2)
  **Status:** Stabilní
  **Endpoint:** `/versioned/v2`
-  
-  Toto je aktuální a doporučená verze API. Klikněte na odkaz pro zobrazení kompletní dokumentace pro v2.

- ### [Verze 1 (v1)](../v1)
-  **Status:** Stabilní
+- ### [~Verze 1 (v1)~](../v1)
+  **Status:** Deprecated
  **Endpoint:** `/versioned/v1`

+  Verze 1 bude v budoucnu odstaněna. Migrujte na novější verze
+
 ---

 ## Nezařazené Endpointy
--- a/web/content/posts/api/v1/index.md
+++ b/web/content/posts/api/v1/index.md
@@ -5,6 +5,10 @@ tags: ["api", "docs", "v1"]
 hiddenInHomelist: true
 ---

+{{< admonition type="warning" title="Deprecated" >}}
+Tato verze je **deprecated**. Prosím nepoužívejte ji, bude brzy odstraněna.
+{{< /admonition >}}
+
 Tato stránka detailně popisuje **Verzi 1 (v1)** API Ječná Rozvrh.

 ## Endpoint: `GET /versioned/v1`
@@ -39,7 +43,7 @@ Tato sekce je pole, kde každý prvek představuje jeden den. Každý den je obj
 - **Klíč:** Název třídy (např. `"A1"`)
 - **Hodnota:** Pole s 10 prvky, které reprezentují 10 vyučovacích hodin.
  - `string`: Pokud je hodina normálně vyučována, obsahuje název předmětu nebo informaci o změně.
-  - `null`: Pokud hodina odpadá nebo pro ni není záznam.
+  - `null`: Pokud pro ni není záznam.
  - Text `(bude upřesněno)` může být připojen k předmětu, pokud je změna nejistá.

 <details>
--- a/web/content/posts/api/v2/index.md
+++ b/web/content/posts/api/v2/index.md
@@ -39,7 +39,7 @@ Tato sekce je pole, kde každý prvek představuje jeden den. Každý den je obj
 - **Klíč:** Název třídy (např. `"A1"`)
 - **Hodnota:** Pole s 10 prvky, které reprezentují 10 vyučovacích hodin.
  - `string`: Pokud je hodina normálně vyučována, obsahuje název předmětu nebo informaci o změně.
-  - `null`: Pokud hodina odpadá nebo pro ni není záznam.
+  - `null`: Pokud pro ni není záznam.
  - Text `(bude upřesněno)` může být připojen k předmětu, pokud je změna nejistá.

 <details>
--- a/web/content/posts/api/v3/index.md
+++ b/web/content/posts/api/v3/index.md
@@ -0,0 +1,193 @@
+---
+title: "API Dokumentace - Verze 2"
+date: 2026-01-28
+tags: ["api", "docs", "v2"]
+hiddenInHomelist: true
+---
+
+Tato stránka detailně popisuje **Verzi 2 (v2)** API Ječná Rozvrh.
+
+## Endpoint: `GET /versioned/v3`
+
+Toto je hlavní endpoint, který poskytuje veškerá data o rozvrhu pro v2.
+
+### Struktura Odpovědi
+
+Odpověď je JSON objekt, který obsahuje dva hlavní klíče: `schedule` a `status`.
+
+<details>
+<summary>Zobrazit příklad struktury odpovědi</summary>
+
+```json
+{
+  "schedule": { /* objekt denních rozvrhů */ },
+  "status": { /* objekt stavu */ }
+}
+```
+</details>
+
+---
+
+### Datové Struktury
+
+#### Sekce: `schedule`
+
+Tato sekce je objekt, kde každý klíč představuje datum ve formátu `YYYY-MM-DD` a prvek představuje jeden den. Každý den je objekt, jehož klíče jsou `info`, `changes`, `absence`, `takesPlace` a `reservedRooms`
+
+##### `changes`
+- Objekt
+- **Klíč:** Název třídy (např. `"A1"`)
+- **Hodnota:** Pole s 10 prvky, které reprezentují 10 vyučovacích hodin.
+  - Objekt: Pokud je hodina normálně vyučována, obsahuje název předmětu nebo informaci o změně.
+  - `null`: Pokud pro ni není záznam.
+
+Hodnota je následující objekt
+
+```ts
+{
+  text: string,
+  backgroundColor?: string,
+  foregroundColor?: string,
+  willBeSpecified?: boolean
+}
+```
+
+<details>
+<summary>Zobrazit příklad rozvrhu pro třídu A1</summary>
+
+```json
+"A1": [
+  {
+    "text": "M 5 Kp(Ng)"
+  },
+  null,
+  null,
+  {
+    "text": "M 5 odpadá",
+    "backgroundColor": "#DCEDD5",
+    "foregroundColor": "#FF000000"
+  },
+  null,
+  null,
+  null,
+  null,
+  null,
+  null
+]
+```
+</details>
+
+##### `absence`
+- Pole objektů, kde každý objekt specifikuje jednu absenci. Struktura objektu je následující:
+  - `teacher` (string | null): Celé jméno učitele, pokud je známé.
+  - `teacherCode` (string | null): Zkratka jména učitele (např. "me", "ad").
+  - `type` (string): Typ absence. Může nabývat následujících hodnot:
+    - `"wholeDay"`: Učitel chybí celý den.
+    - `"single"`: Učitel chybí jednu vyučovací hodinu.
+    - `"range"`: Učitel chybí v rozmezí několika hodin.
+    - `"exkurze"`: Učitel je na exkurzi.
+    - `"invalid"`: Záznam o absenci se nepodařilo zpracovat.
+  - `hours` (object | number | null): Specifikuje hodiny absence.
+    - `null`: Pro typy `wholeDay`, `exkurze`, a `invalid`.
+    - `number` (např. `3`): Pro typ `single`.
+    - `object` (např. `{ "from": 2, "to": 4 }`): Pro typ `range`.
+  - `original` (string | null): Pouze pro typ `invalid`, obsahuje původní nezpracovaný text.
+
+<details>
+<summary>Zobrazit příklady absencí</summary>
+
+**Celý den:**
+```json
+{
+  "teacher": "Jan Novák",
+  "teacherCode": "no",
+  "type": "wholeDay",
+  "hours": null
+}
+```
+
+**Jedna hodina:**
+```json
+{
+  "teacher": "Jan Novák",
+  "teacherCode": "no",
+  "type": "single",
+  "hours": 1
+}
+```
+
+**Rozsah hodin:**
+```json
+{
+  "teacher": "Jan Novák",
+  "teacherCode": "no",
+  "type": "range",
+  "hours": { "from": 2, "to": 4 }
+}
+```
+
+**Exkurze:**
+```json
+{
+  "teacher": "Jan Novák",
+  "teacherCode": "no",
+  "type": "exkurze",
+  "hours": null
+}
+```
+
+**Zastupuje:**
+```json
+{
+  "teacher": "Ing. Zdeněk Vondra",
+  "teacherCode": "vn",
+  "type": "zastoupen",
+  "hours": null,
+  "zastupuje": {
+    "teacher": "David Janoušek",
+    "teacherCode": "jk",
+  },
+},
+```
+
+**Neplatný záznam:**
+```json
+{
+  "type": "invalid",
+  "teacher": null,
+  "teacherCode": null,
+  "hours": null,
+  "original": "Nezpracovatelný text"
+}
+```
+</details>
+
+##### `takesPlace`
+
+String obsahující aktuálně probíhající akce ten den.
+
+#### `reservedRooms`
+
+Pole 10 prvků (string | null) pro jakou hodinu jsou rezervované jaké místnosti.
+
+#### `info.inWork`
+
+Boolean jestli je daná tabulka in work (příprava).
+
+#### Sekce: `status` - Stav a Metadata
+
+Objekt poskytující informace o aktuálnosti dat.
+
+- `lastUpdated` (string): Čas poslední úspěšné aktualizace dat ve formátu `HH:MM`.
+- `currentUpdateSchedule` (number): Interval v **minutách**, ve kterém scraper interně kontroluje a stahuje novou verzi rozvrhu. Tento interval se dynamicky mění v závislosti na denní době (kratší během vyučování, delší v noci).
+
+<details>
+<summary>Zobrazit příklad status</summary>
+
+```json
+"status": {
+  "lastUpdated": "08:30",
+  "currentUpdateSchedule": 5
+}
+```
+</details>
--- a/web/content/posts/self-hosting/index.md
+++ b/web/content/posts/self-hosting/index.md
@@ -10,7 +10,7 @@ Tento projekt je možné hostovat vlastním způsobem, ať už pomocí Dockeru n

 Před začátkem se ujistěte, že máte připravené následující:

- **Účet SPŠ Ječná**: Projekt vyžaduje platný školní e-mail a heslo pro přístup k tabulce na SharePointu.
+- **Účet SPŠE Ječná**: Projekt vyžaduje platný školní e-mail a heslo pro přístup k tabulce na SharePointu.
 - **Node.js 22+**: Pokud hostujete nativně.
 - **Hugo**: Pro sestavení a provoz webového rozhraní.
 - **Chromium/Puppeteer**: Pro automatizované stahování dat.
--- a/web/layouts/shortcodes/admonition.html
+++ b/web/layouts/shortcodes/admonition.html
@@ -0,0 +1,78 @@
+{{ $type := .Get "type" | default "note" }}
+{{ $title := .Get "title" | default (print (title $type)) }}
+
+<div class="alert alert-{{ $type }}">
+  <div class="alert-title">
+    {{ $title }}
+  </div>
+
+  <div class="alert-content">
+    {{ .Inner | markdownify }}
+  </div>
+</div>
+
+<style>
+.alert {
+  margin: 1.5rem 0;
+  padding: 1rem;
+  border-left: 4px solid;
+  border-radius: 0.5rem;
+  background-color: #2e2e33;
+  color: #ebebeb;
+}
+
+/* Title */
+.alert-title {
+  font-weight: 600;
+  margin-bottom: 0.5rem;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 2rem;
+}
+
+.alert-content {
+  font-size: 1.1rem;
+  line-height: 1.6;
+  max-width: 100%;
+}
+
+.alert-content p {
+  margin: 0.5em 0;
+}
+
+.alert-content a {
+  color: #7dd3fc;
+  text-decoration: underline;
+}
+
+.alert-content code {
+  background: #2a2a2a;
+  padding: 0.15em 0.35em;
+  border-radius: 4px;
+  font-size: 0.85em;
+}
+
+.alert-content pre {
+  background: #111;
+  padding: 0.75rem;
+  border-radius: 6px;
+  overflow-x: auto;
+}
+
+.alert-note {
+  border-color: #31929A;
+}
+
+.alert-warning {
+  border-color: #eab308;
+}
+
+.alert-danger {
+  border-color: #ef4444;
+}
+
+.alert-success {
+  border-color: #22c55e;
+}
+</style>