Návody FIT
Jdi na navigaci

Tvorba obsahu

Výslednou podobu předmětové stránky na https://courses.fit.cvut.cz/ nevytváří vyučující přímo, ale je generována automaticky platformou Courses z tzv. zdrojového repozitáře. Tento repozitář najde vyučující zpravidla v předmětové skupině.

Postup, jakým probíhá úprava předmětové stránky, lze zjednodušeně shrnout do následujících kroků:

  1. Vyučující tvoří a upravuje obsah v tzv. zdrojovém repozitáři na GitLabu.[1]
  2. Po uložení změn Courses automaticky vygeneruje výslednou podobu předmětové stránky.[2]
  3. Po dokončení je stránka automaticky publikována na https://courses.fit.cvut.cz/ v konkrétním předmětu.
gen process.cs
Obrázek 1. Proces úpravy předmětu na Courses. Zjednodušeně.

Zdrojový repozitář

Repozitář, ze kterého je předmětová stránka generována, naleznete následujícím způsobem:

  1. Přihlaste se do služby GitLab.
  2. Přejděte do skupiny konkrétního předmětu.[3]
  3. V předmětové skupině přejděte do repozitáře s předmětovými stránkami.[4]
Upozornění:

Tento repozitář můžete upravovat na základě přidělených práv.[5]

V již existujícím předmětu lze obsah tvořit několika způsoby:

  • Jednoduché úpravy lze provádět přímo ve webovém prostředí bez nutnosti hlubších znalostí nebo instalace jakýchkoli aplikací. Více viz Webový editor.
  • Složitější úpravy (jako např. hromadné) je doporučeno provádět lokálně s pomocí vzdáleného přístupu a gitu. Více viz Lokální úpravy.

Webový editor

Pro tvorbu obsahu ve webovém prostředí je využíváno rozhrání GitLab.

Proces publikování vašich změn se spustí automaticky po provedení commit, viz poslední krok sekce Úprava souborů.

Lokální úpravy

Pro pokročilou práci nebo hromadné úpravy je doporučeno provádět úpravy následujícím postupem. Tento postup zároveň přímočaře umožňuje náhled změn ještě před publikováním.

  1. Stáhněte Generátor Course Pages.
  2. Stáhněte zdrojový repozitář daného předmětu.[6]
  3. V kořenovém adresáři staženého repozitáře spusťte Generátor Course Pages.
    1. Jednorázové spuštění course-pages public.
    2. Spuštění se sledováním změn course-pages --watch public (automaticky vygeneruje náhled po každé změně).
  4. Výslednou podobu (resp. její náhled) naleznete v adresáři staženého repozitáře ve složce public, konkrétně v souboru index.html.
    1. Soubor lze zobrazit v libovolném webovém prohlížeči, po každé změně je v něm stránku potřeba obnovit například stiskem Ctrl+R.
  5. Zveřejnění změn provedete pomocí nahrání změn[7] do předmětového repozitáře, a to posloupností příkazů:
    1. git add .
    2. git commit -m "<Stručný popis změn>"
    3. git push

Podporované formáty

Jednou z vlastností platformy je možnost výběru formátu, ve kterém budete stránky předmětů vytvářet a upravovat. Formáty lze v rámci jednoho předmětu libovolně kombinovat.[8][9]

Podporovanými formáty v současnosti jsou:

Částečně podporované formáty:

Náhled úprav

Při editaci AsciiDoc a Markdown souborů na GitLabu si můžete zobrazit náhled přibližné výsledné podoby v záložce Preview. Tento základní náhled však nemusí přesně odpovídat finální podobě, která bude publikována na Courses. V případě používání Web IDE není náhled možný.

Další z možností náhledu změn před publikováním je vygenerovat podobu předmětové stránky lokálně. Takovýto náhled již reflektuje finální podobu, která bude publikována na Courses.

Existují však další způsoby náhledu, které lze provést bez nutnosti repozitář stahovat. Více viz Větve.

Větve

Pokud potřebujete mimo hlavní vývojovou větev průběžně pracovat na vaší předmětové stránce – vytvořte nejdříve novou větev.[10] Více k vytváření větví viz Vytvoření větve.

Všechny změny provedené v konkrétní větvi se publikují na adresu předmětové stránky s příponou @<název větve>.[11]

Příklad použití větve

Potřebuji pracovat na přípravách pro nadcházející semestr. Z pochopitelných důvodů nechci změny ihned publikovat, ale chci dát kolegům možnost do změn nahlédnout a přispívat.

Pro předmět MI-XYZ vytvořím větev s názvem pripravy-na-B202, do které budu ukládat přípravu na nadcházející semestr. Do větve mohou kolegové libovolně přispívat. Vždy aktuální náhled změn naleznu na adrese https://courses.fit.cvut.cz/MI-XYZ/@pripravy-na-B202

Po vytvoření Merge request je možné vést diskuzi s kolegy nad jednotlivými změnami.

Jakmile je daný merge request přijat (proběhl merge do větve master), dojde automaticky ke zveřejnění změn v cílové větvi.

Postranní navigace zobrazuje všechny soubory, které se nacházejí v repozitáři stránek předmětu, nezávisle na jejich typu.

Pokud se jedná o podporovaný formát souboru, je v navigaci uveden odkaz na vykreslený HTML soubor. Pokud formát podporovaný není, je v navigaci uveden odkaz ke stažení. Chování navigace je možné ovlivnit v nastavení – například skrýt požadované soubory.

Názvy položek

Navigace se snaží zobrazit co nejvhodnější název. Pokud má soubor uveden titulek[12], je použit i v navigaci, jinak se zobrazí název souboru.

V případě adresáře se generátor pokusí nalézt soubor index.*. Pokud má index soubor uveden titulek, je použit jako název položky v navigaci.

Níže je demonstrováno chování navigace. Soubor title-available.adoc má uvnitř nastaven titulek „Titulkem opatřený soubor“ a soubor folder-with-index/index.adoc má titulek „Složka s indexem“.

navfolder.cs
Obrázek 2. Ukázka chování titulků navigace (vlevo adresářová struktura, vpravo výsledné menu).
  1. Při tvorbě obsahu je doporučeno dodržovat pevně stanovené konvence, vizte např. konvence dodržované na těchto stránkách. ↩
  2. Tento proces může trvat několik minut. ↩
  3. URL předmětové skupiny je standardně ve tvaru https://gitlab.fit.cvut.cz/BI-XYZ/ ↩
  4. Název repozitáře stránky předmětu standardně začíná kódem předmětu. ↩
  5. Pokud nedisponujete právy předmětové stránky upravovat, obraťte se na vlastníka repozitáře (zpravidla garant předmětu). ↩
  6. Stažení (resp. klonování) zdrojového repozitáře provedete stejně, jako klonování jakéhokoliv jiného repozitáře. Postup viz Lokální práce s repozitářem. ↩
  7. Žádáme uživatele, aby zbytečně neprováděli s každou změnou git push, a šetřili tím tak výpočetní prostředky. ↩
  8. Formát souboru generátor rozezná automaticky podle přípony souboru. ↩
  9. Nelze je však kombinovat v rámci jednoho souboru. ↩
  10. Název větve volte libovolný. ↩
  11. Jedním ze speciálních příkladů použití větví jsou větve semestrů – tyto větve jsou vytvářeny automaticky. ↩
  12. Jak nastavit titulek je uvedeno u konkrétních typů obsahu. Například jak nastavit titulek v AsciiDoc viz Metadata a atributy ↩