\chapter{Webová dokumentace} \label{kapitola:webova-dokumentace}

Jedním z~výstupů této práce je dokumentace, která poskytuje nejen návod k~přípravě a~provozu zařízení, ale také obsahuje ukázky projektů, na nichž lze zařízení využít. Tyto příklady, uvedené v~kapitole \ref{kapitola:didakticke-materialy}, mohou učitelé začlenit do výuky jako inspiraci nebo přímo jako úkoly pro studenty.

Tato sekce se věnuje procesu tvorby, úpravy a~publikování webové verze didaktických materiálů. Poskytuje uživatelům informace potřebné k~vytvoření vlastních verzí těchto materiálů, přizpůsobených specifickým potřebám výuky, včetně přidání vlastního obsahu a~úkolů. Zároveň slouží jako návod, jak provádět změny v~oficiální webové dokumentaci, dostupné na adrese \url{https://docs.capyboard.dev}.

Oficiální dokumentace je otevřena k~úpravám veřejnosti, která může své změny navrhovat prostřednic\-tvím standardních \uv{pull requestů} v~repozitáři \url{https://github.com/realcharmer/capyboard-docs}. Tento přístup umožňuje širší komunitě přispívat k~obohacování obsahu a~zajišťuje pravidelnou aktualizaci materiálů podle aktuálních potřeb a~podnětů z~praxe.

Fyzické učebnice, jako je například zmíněná učebnice \emph{ARDUINO PROJECTS BOOK}, mají své nezbytné výhody, ale také několik nevýhod, které omezují jejich efektivitu v~moderním vzdělávání. Jednou z~hlavních nevýhod je jejich statický charakter. Obsah fyzických učebnic není aktualizován, což může znamenat zastaralé informace a~nedostatečné pokrytí nových technologických vývojů, například softwarových knihoven. Fyzické učebnice jsou zároveň vázány na fyzický nosič (papír), což ztěžuje sdílení obsahu mezi studenty, a~mohou být i~finančně náročné.

Naproti tomu, vytvoření interaktivní webové stránky jako alternativy k~fyzické učebnici přináší řadu výhod. Webové stránky umožňují snadnou aktualizaci obsahu a~jeho okamžité zpřístupnění všem uživatelům. Interaktivní prvky mohou usnadnit orientaci v~obsahu, vyhledávání, či práci s~ukázkami kódu, který je možné jednoduše kopírovat.

Digitální vzdělávací materiály mohou pozitivně ovlivnit motivaci studentů a~zlepšit jejich výsledky ve srovnání s~tradičními metodami výuky. Vytváření digitálních studijních materiálů s~otevřenou licencí a~možností jejich úprav podle potřeb konkrétních skupin žáků je důležitý prvek efektivního vzdělávacího procesu. Tato flexibilita umožňuje pedagogům přizpůsobit obsah tak, aby odpovídal rozdílným úrovním znalostí a~individuálním potřebám studentů. \parencite{digcompedu}


\section{Výběr vhodné technologie}

Pro tvorbu dokumentace existuje několik možných přístupů. Jedním z~nich je využití dynamické webové aplikace ve stylu \uv{wiki} s~databází. Nicméně takové systémy jsou často zbytečně složité pro většinu použití, a~je proto výhodnější zvolit některý z~funkčních generátorů statických webových stránek. Tím nejen získáme rychlejší výslednou webovou stránku, ale zároveň se vyhneme potřebě provozování databázového systému a~případně také webového serveru, nýbrž statickou stránku lze také používat lokálně bez nutnosti připojení k~internetu. \parencite{buckler2021}

Nabízí se celá řada takových generátorů. Ty nejpoužívanější z~nich mohou být například:

\begin{table}[htbp]
    \centering
    \vspace{15pt}
    \begin{tabular}{llllc}
        \textbf{Název} & \textbf{Jazyk} & \textbf{Jazyk šablon} & \textbf{Jazyk vstupu} & \textbf{Vícejazyčná podpora} \\
        \midrule
        mdBook & Rust & Tera & Markdown & \symbolcross\footnotemark \\
        MkDocs & Python & Jinja2 & Markdown & \symbolcheck \\
        Docusaurus & JavaScript & React & Markdown & \symbolcheck \\
        Zola & Rust & Tera & Markdown & \symbolcheck \\
    \end{tabular}
    \vspace{10pt}
\end{table}

\footnotetext{Podpora více jazyků není v~tuto chvíli implementována, viz \url{https://github.com/rust-lang/mdBook/issues/5}}

Do tohoto seznamu lze zahrnout i~spoustu dalších generátorů, které nejsou přímo určené pro tvorbu dokumentace, avšak nabízejí pro tento účel připravené šablony. Je jich však tolik a~tak často se jejich nabídka mění, že není praktické je zde vypisovat všechny. Při výběru vhodného generátoru záleží hlavně na preferencích uživatele, tedy autora dokumentace. Důležitá je i~softwarová podpora, protože některé systémy mohou být složitější na instalaci či zakomponování do automatizovaných CI\footnotemark{} systémů než jiné.

\footnotetext{Continuous Integration -- Automatická správa a~integrace zdrojového kódu. V~kontextu webových stránek často slouží ke kompilaci a~publikaci výsledného webu.}

Použití statického generátoru může rovněž výrazně snížit bezpečnostní rizika, která jsou charakteristická pro dynamické webové aplikace. Jak uvádí dokument \emph{OWASP Top Ten} \parencite{owasp}, který se zaměřuje na analýzu nejběžněji využívaných typů útoků na webové aplikace, statické webové stránky eliminují mnoho potenciálních bezpečnostních hrozeb tím, že minimalizují možnosti pro útoky, jako jsou \emph{SQL injection} nebo \emph{cross-site scripting (XSS)}. Využitím statické webové stránky se tedy aktivně předchází podobným typům zranitelností.

Ze zmíněných systémů byl autorem práce vybrán systém MkDocs. Hlavním důvodem pro jeho zvolení je jeho jednoduchost, uživatelská přívětivost a~vícejazyčná podpora. Kromě toho existuje rozšíření, resp. alternativní verze s~názvem \emph{Material for MkDocs}\footnote{\url{https://squidfunk.github.io/mkdocs-material/}}, která nabízí oproti původnímu systému MkDocs moderní a~atraktivní uživatelské rozhraní.

Důležitým aspektem při výběru MkDocs byla také jeho podpora a~dostupnost rozsáhlé dokumentace a~sada rozšíření. Použití MkDocs a~Material for MkDocs tak představuje výhodnou kombinaci jednoduchosti, funkčnosti a~vizuální atraktivity, což přispívá k~efektivní tvorbě a~správě technické dokumentace, ale také k~jejímu snadnému užívání z~pohledu učitele i~žáků.


\section{Instalace a~vývoj}

Instalace systému MkDocs, resp. Material for MkDocs, je relativně snadná a~intuitivní, což umožňuje její rychlé zprovoznění. Stačí se řídit oficiální dokumentací \parencite{mkdocs-material}.

Existuje několik možných způsobů instalace. Každý z~těchto způsobů instalace má své výhody a~nevý\-hody, a~volba konkrétní metody závisí na specifických potřebách a~preferencích uživatele. Je tedy možné instalaci těmito způsoby:

\begin{enumerate}
    \item Přímo do systému s~využitím systémových Python knihoven
    \item S~využitím virtuálního prostředí Python Virtual Environment
    \item Pomocí oficiálního kontejneru v~systému Docker
\end{enumerate}

\subsection*{Systémová instalace} \label{sekce:mkdocs-instalace}

První přístup, tedy instalace přímo do systému, je jednoduchý, ale může způsobit konflikty mezi verzemi knihoven, pokud je na systému nainstalováno více Python aplikací. Je možné jej provést snadno, a~to pomocí nástroje \emph{pip}.

\emph{Pip} je nástroj, který umožňuje instalaci a~správu softwarových balíčků napsaných právě v~jazyce Python. Umožňuje snadné stahování a~instalaci knihoven a~dalších závislostí z~PyPI (Python Package Index) a~zajišťuje, že všechny potřebné komponenty jsou správně nainstalovány. \parencite{python-pip}

Instalace MkDocs a~Material for MkDocs pomocí \emph{pip} je možná jednoduchým příkazem:

\begin{minted}{bash}
pip install mkdocs-material mkdocs-awesome-pages-plugin
\end{minted}

Příkaz stáhne a~nainstaluje MkDocs spolu s~potřebnými závislostmi. Zároveň je nainstalováno rozšíření \emph{MkDocs Awesome Pages Plugin}\footnote{\url{https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin}}, které je v~dokumentaci využíváno pro systematické řazení jednotlivých stránek v~navigaci. Tento typ instalace je vhodný pro uživatele, kteří chtějí rychle začít pracovat bez potřeby nastavení virtuálního prostředí nebo kontejnerizace.

\subsection*{Python Virtualenv}

Druhou možností je využití virtuálního prostředí pomocí \emph{Python Virtual Environment}, známého pod názvem \emph{Virtualenv} nebo \emph{Venv}. Ten umožňuje vytvořit oddělené prostředí, kde jsou všechny závislosti a~balíčky nainstalovány lokálně, aniž by ovlivňovaly globální systémové nastavení.

Po aktivaci virtuálního prostředí se všechny příkazy \emph{pip} a~\emph{python} vztahují pouze k~tomuto izolovanému prostředí, což usnadňuje správu závislostí a~verzí knihoven. Tento přístup je obzvláště vhodný pro vývojáře, kteří potřebují konzistentní a~kontrolované prostředí pro každý svůj projekt, čímž se minimalizuje riziko konfliktů mezi různými verzemi balíčků. \parencite{python-venv}

Postup instalace MkDocs pomocí \emph{Venv} zahrnuje následující kroky:

\begin{minted}{bash}
python -m venv venv
source venv/bin/activate
pip install mkdocs-material mkdocs-awesome-pages-plugin
\end{minted}

V~obou případech je následně možné spouštět systém MkDocs, a~to následujícími příkazy s~různými možnostmi a~funkcionalitou:

\begin{itemize}
    \item \verb|mkdocs new [dir-name]| - Vytvoření nového projektu.
    \item \verb|mkdocs serve| - Spuštění lokálního serveru s~náhledem webových stránek.
    \item \verb|mkdocs build| - Vygenerování výsledných souborů pro publikaci na webu.
\end{itemize}

\subsection*{Docker}

Další možností je instalace pomocí oficiálního kontejneru v~systému Docker. Tento způsob je vhodný pro uživatele, kteří chtějí izolovat instalaci od zbytku systému pomocí kontejnerizace. Docker umožňuje snadné nasazení a~spuštění MkDocs bez ohledu na hostitelské prostředí. Na druhou stranu však způsobuje náročnější postup při instalaci možných rozšíření systému. Hodí se tedy hlavně do automatizace, která může výsledné webové stránky generovat a~publikovat, viz sekce \ref{sekce:web-ci}.

\emph{Docker} je platforma pro kontejnerizaci, která umožňuje balení aplikací a~jejich závislostí do kontejnerů. Kontejnery jsou lehké, přenosné a~konzistentní prostředí, která zajišťují, že aplikace poběží stejným způsobem bez ohledu na to, kde jsou nasazeny. Docker zjednodušuje vývoj, testování a~nasazení aplikací tím, že eliminuje problémy způsobené rozdíly mezi vývojovým a~produkčním prostředím.

Použití Dockeru zajišťuje, že aplikace běží v~izolovaném prostředí, což minimalizuje problémy s~kompatibilitou a~závislostmi. Tento přístup je ideální pro vývojáře a~týmy, které potřebují konzistentní a~reprodukovatelné prostředí pro své aplikace. Docker navíc usnadňuje škálování a~nasazení aplikací na různé platformy a~infrastruktury, což zvyšuje flexibilitu a~efektivitu práce. \parencite{docker}

Pro instalaci Material for MkDocs pomocí Dockeru stačí použít oficiální kontejner. Postup zahrnuje stažení obrazu kontejneru z~knihovny \emph{Docker Hub} a~následovné vytvoření a~spuštění funkčního kontejneru. Příkaz pro stažení kontejneru vypadá následovně:

\begin{minted}{bash}
docker pull squidfunk/mkdocs-material
\end{minted}

Protože výchozím zdrojem pro kontejnery v~systému Docker je právně knihovna \emph{Docker Hub}, není nutné zde specifikovat adresu a~stačí pouze název samotného kontejneru. Spuštění lze pak provést například tímto příkazem:

\begin{minted}[breaklines]{bash}
docker run --rm -it -p 127.0.0.1:8000:8000 -v ${PWD}:/docs -u $(id -u):$(id -g) squidfunk/mkdocs-material serve
\end{minted}

\begin{itemize}
    \item \verb|--rm| zajistí, že kontejner bude automaticky odstraněn po ukončení.
    \item \verb|-it| umožňuje interaktivní mód.
    \item \verb|-p 127.0.0.1:8000:8000| zajistí správné namapování síťového portu 8000 do kontejneru, což je nutné pro správné fungování příkazu \verb|serve|.
    \item \verb|-v ${PWD}:/docs| připojuje aktuální pracovní adresář na hostitelském systému do adresáře \emph{/docs} uvnitř kontejneru.
    \item \verb|-u $(id -u):$(id -g)| mapují UID a~GID uživatele do kontejneru, čímž se zajistí, že vytvořené soubory bude vlastnit stávající uživatel, nikoliv uživatel \emph{root}.
    \item \verb|squidfunk/mkdocs-material| specifikuje název kontejneru pro jeho stažení z~\emph{Docker Hub}.
    \item \verb|serve| specifikuje akci, kterou má systém MkDocs vykonat (v~tomto případě vytváření živého náhledu skrze lokální webový server).
\end{itemize}

Je nutné podotknout, že stažení kontejneru se provede automaticky, pokud se uživatel snaží kontejner spustit bez jeho předchozího manuálního stažení. Docker v~tomto případě nejprve stáhne požadovaný obraz z~Docker Hubu a~následně spustí kontejner s~tímto obrazem. Je tedy možné první krok stažení vynechat.

Pokud se uživateli zdá zmíněný příklad pro spuštění kontejneru složitý, a~to oprávněně, je možné si pro něj vytvořit alias v~systémovém Shellu, například:

\begin{minted}[breaklines]{bash}
alias mkdocs="docker run --rm -it -p 127.0.0.1:8000:8000 -v ${PWD}:/docs -u $(id -u):$(id -g) squidfunk/mkdocs-material"
\end{minted}

Tímto způsobem je možné se vyhnout nutnosti zadávat dlouhý a~komplikovaný příkaz při každém spuštění kontejneru. V~takovém případě pak z~pohledu běžného uživatele nelze rozeznat, v~jakém prostředí je aplikace nainstalována. 


\section{Struktura a~obsah}

Obsah celé dokumentace se podobá běžné technické dokumentaci, která je často využívána v~mnoha softwarových i~hardwarových projektech. Obsah je rozdělen do jednotlivých hlavních sekcí, které jsou logicky členěny dle povahy obsahu. Tato struktura je nejen přehledná, ale také představuje standardní přístup ke strukturování dokumentace. Tento přístup usnadňuje orientaci a~používání dokumentace díky své konzistenci a~srozumitelnosti. Poukazují na to články, které se touto problematikou zabývají, například články \emph{How to write technical documentation} \parencite{documentation-ashby}, nebo \emph{5 Steps to Create Technical Documentation That’s (Actually) Helpful} \parencite{documentation-mackay}.

Struktura dokumentace je navržena tak, aby pokrývala všechny aspekty projektu, včetně technických specifikací, návodů k~instalaci, konfigurace a~použití. Díky tomuto uspořádání mohou uživatelé snadno nalézt potřebné informace a~rychle se zorientovat v~jejím obsahu. Hlavní sekce zahrnují:

\begin{itemize}
    \item Úvod
    \item Instalace a~konfigurace softwaru
    \item Příprava zařízení a~jeho ovládání
    \item Přehled jednotlivých modulů
    \item Ukázkové programy pro práci s~vývojovou deskou a~moduly
\end{itemize}

Sekce s~ukázkovými příklady obsahuje příklady pro každý modul, které lze aplikovat ve výuce. Uži\-va\-te\-lům, respektive učitelům, je tedy poskytován ucelený pohled na zařízení a~jeho možnosti, ale také praktické návody a~příklady, které pomáhají efektivně využívat dané zařízení ve výuce a~usnadňují její přípravu. Viz předchozí kapitola \ref{kapitola:didakticke-materialy}.

Z~technického hlediska je struktura dokumentace následující:

\begin{itemize}
    \item Složka \verb|docs| obsahuje samotný obsah, ze kterého se generují výsledné webové stránky.
    \item Soubor \verb|mkdocs.yml|, který obsahuje základní konfiguraci projektu.
    \item Soubor \verb|.gitignore|, který zajišťuje, že některé soubory a~složky nebudou ukládány do Git repozitáře (například složka pro Python Venv).
\end{itemize}

MkDocs tedy generuje výsledné statické webové stránky ze zdrojového textu nacházejícího se ve složce \emph{docs}, které je možné následně publikovat na jakýkoliv webový server.

Zdrojové soubory dokumentace lze najít v~Git repozitáři dostupném na adrese \url{https://github.com/realcharmer/capyboard-docs}. Pro získání obsahu repozitáře je nejprve nutné provést klonování pomocí následujícího příkazu:

\begin{minted}{bash}
git clone https://github.com/realcharmer/capyboard-docs
\end{minted}

Tímto způsobem je možné získat kompletní dokumentaci ve formátu vhodném pro další úpravy a~publikaci. Aktuální verze dokumentace je však také dostupná na adrese \url{https://docs.capyboard.dev} bez nutnosti klonování repozitáře a~instalace programu MkDocs. Její generování a~publikace jsou popsány v~následující kapitole.


\section{Automatické publikování} \label{sekce:web-ci}

Aby nebylo třeba při každé změně obsahu dokumentace instalovat systém MkDocs, ručně generovat soubory webových stránek a~kopírovat je na webserver, je možné využít automatizovaných procesů, často nazývaných \emph{Actions}. Tyto procesy mohou být spouštěny v~různých situacích, například při nahrání nových změn do Git repozitáře, a~mohou provádět rozmanité a~složité úkony.

\begin{listing}[!ht]
\vspace{10pt}
\caption{YAML konfigurace pro automatické generování a~publikování pomocí \emph{GitHub Actions}}
\label{src:actions}
\begin{minted}[linenos]{yaml}
name: Build

on:
  push:
    branches:
      - master

env:
  HOST: ${{ secrets.SSH_HOSTNAME }}
  HOST_DIR: ${{ secrets.SSH_TARGET_DIR }}
  SSH_USERNAME: ${{ secrets.SSH_USERNAME }}
  SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        run: |
          git clone https://github.com/realcharmer/capyboard-docs.git .

      - name: Install MkDocs
        run: |
          pip install mkdocs-material mkdocs-awesome-pages-plugin

      - name: Build
        run: |
          mkdocs build

      - name: Deploy
        run: |
          eval "$(ssh-agent -s)"
          echo "${SSH_PRIVATE_KEY}" | ssh-add -
          mkdir -p ~/.ssh/
          ssh-keyscan -H "${HOST}" >> ~/.ssh/known_hosts
          rsync -ra --delete-after site/ "${SSH_USERNAME}@${HOST}:${HOST_DIR}"
\end{minted}
\end{listing}

Tyto kroky se obvykle provádějí uvnitř izolovaného kontejneru, známého jako \emph{runner}, který je pro každý průběh procesu nově vytvořen. Tento postup zaručuje konzistenci prostředí při každém běhu, což minimalizuje riziko problémů s~tzv. \uv{znečištěním} prostředí předchozími běhy.

Konfigurace uvedená v~ukázce \ref{src:actions} slouží jako praktický příklad nastavení procesu generování a~publikace navržené webové aplikace. Tato konfigurace je kompatibilní nejen se systémem GitHub Actions, ale lze ji přizpůsobit i~jiným nástrojům, jako jsou \emph{Gitea} nebo \emph{Forgejo}. Konfigurační proces se skládá z~několika kroků, přičemž první část určuje podmínky, za kterých má být proces spuštěn.

\begin{minted}{yaml}
on:
  push:
    branches:
      - master
\end{minted}

Tajné proměnné v~systému \emph{GitHub Actions}, v~angličtině známé pod názvem \uv{secrets}, jsou citlivá data, jako například přístupové klíče, hesla nebo API tokeny, které mohou být použity v~rámci automatizovaných procesů (původním názvem \emph{workflow}) pro přístup k~externím službám nebo k~nastavení při běhu automatizovaných procesů.

\begin{minted}{yaml}
env:
  HOST: ${{ secrets.SSH_HOSTNAME }}
  HOST_DIR: ${{ secrets.SSH_TARGET_DIR }}
  SSH_USERNAME: ${{ secrets.SSH_USERNAME }}
  SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
\end{minted}

Tyto tajné informace jsou uloženy zašifrovaně a~jsou předány do běhů těchto procesů prostřednictvím proměnných, což umožňuje ochranu citlivých informací a~zabezpečení automatizovaných operací. Ukázkový workflow používá následující tajné proměnné:

\begin{table}[htbp]
    \centering
    \vspace{15pt}
    \begin{tabular}{ll}
        \textbf{Název} & \textbf{Popis} \\
        \midrule
        \verb|SSH_HOSTNAME| & Adresa webového serveru \\
        \verb|SSH_TARGET_DIR| & Cílová složka (kořenová složka webového serveru) \\
        \verb|SSH_USERNAME| & Uživatelské jméno pro SSH \\
        \verb|SSH_PRIVATE_KEY| & Soukromý klíč pro SSH \\
    \end{tabular}
    \vspace{10pt}
\end{table}

Poslední část konfigurace již definuje jednotlivé kroky, které budou vykonávány v~rámci procesu:

\begin{enumerate}
    \item Naklonování obsahu repozitáře
    \item Instalace systému MkDocs, viz kapitola \ref{sekce:mkdocs-instalace}
    \item Vygenerování výsledných souborů webových stránek
    \item Konfigurace SSH a~kopírování souborů na webserver
\end{enumerate}


\section{Barevná schémata} \label{sekce:barevna-schemata}

Studie s~názvem \emph{How Terra improved user engagement thanks to Dark Mode} \parencite{dark-theme-tera} uvádí, že značná část uživatelů dává přednost tmavému pozadí. Výzkum naznačuje, že tmavé pozadí může významně zlepšit uživatelskou zkušenost a~zvýšit zapojení uživatelů na webových stránkách. Preferenci tmavého režimu lze přičíst jeho estetickým vlastnostem a~jeho schopnosti zlepšit čitelnost obsahu na obrazovkách v~prostředí s~nízkým osvětlením.

\begin{figure}[h!]
    \vspace{10pt}
    \centering
    \includegraphics[width=\textwidth]{obrazky/capyboard-dokumentace-light.png}
    \caption{Náhled na příklad ze sekce \ref{sekce:ukazkovy-priklad-tvary} ve světlé verzi.}
    \label{fig:capyboard-dokumentace/light}
    \vspace{10pt}
\end{figure}

Dalším důležitým aspektem, který stojí za popularitou tmavého režimu, je jeho pozitivní vliv na snížení únavy očí. Světlé pozadí při delším používání může vést k~větší zátěži pro oči, zatímco tmavé pozadí působí méně intenzivně a~bývá vnímáno jako příjemnější. Studie dokonce uvádí, že více než polovina uživatelů zažila podráždění očí nebo poškození zraku spojené s~dlouhodobým sledováním obrazovek \parencite{dark-theme-eyestrain}. Tmavý režim tak může přispět ke zmírnění těchto potíží.

Kromě toho tmavé pozadí také přispívá k~menšímu opotřebení displejů s~technologií OLED. Displeje typu OLED také spotřebovávají méně energie při zobrazování tmavých barev, což může vést k~prodloužení jejich životnosti. \parencite{dark-theme-displays}.

\begin{figure}[h!]
    \vspace{10pt}
    \centering
    \includegraphics[width=\textwidth]{obrazky/capyboard-dokumentace-dark.png}
    \label{fig:capyboard-dokumentace-dark}
    \caption{Náhled na příklad ze sekce \ref{sekce:ukazkovy-priklad-tvary} ve tmavé verzi.}
    \vspace{10pt}
\end{figure}

Z~těchto důvodů byl tmavý vzhled webové dokumentace zvolen jako výchozí, aby se maximalizoval uživatelský komfort a~efektivita při práci s~dokumentací. Uživatel má však možnost zvolit barevné schéma dle osobních preferencí přepínačem umístěným vlevo od pole pro vyhledávání.