Nette Documentation Preview

syntax 
Jak přispět do dokumentace
**************************

.[perex]
Přispívání do dokumentace je jednou z nejpřínosnějších činností, neboť pomáháte druhým porozumět frameworku.


Jak psát?
---------

Dokumentace je určena především lidem, kteří se s tématem seznamují. Proto by měla splňovat několik důležitých bodů:

- Začněte od jednoduchého a obecného. K pokročilejším tématům přejděte až na konci
- Snažte se věc co nejlépe vysvětlit. Zkuste například téma nejprve vysvětlit kolegovi
- Uvádějte jen ty informace, které uživatel skutečně k danému tématu potřebuje vědět
- Ověřte si, že vaše informace jsou skutečně pravdivé. Každý kód otestujte
- Buďte struční - co napíšete, zkraťte na polovinu. A pak klidně ještě jednou
- Šetřete zvýrazňovači všeho druhu, od tučného písma po rámečky jako `.[note]`
- V kódech dodržujte [Coding Standard]

Osvojte si také [syntax]. Pro náhled článku během jeho psaní můžete použít [editor s náhledem |https://editor.nette.org/].


Jazykové mutace
---------------

Primárním jazykem je angličtina, vaše změny by tedy měly být v češtině i angličtině. Pokud angličtina není vaší silnou stránkou, použijte [DeepL Translator |https://www.deepl.com/translator] a ostatní vám text zkontrolují.

Překlad do ostatních jazyků bude proveden automaticky po schválení a doladění vaší úpravy.


Triviální úpravy
----------------

Pro přispívání do dokumentace je nezbytné mít účet na [GitHub|https://github.com].

Nejjednodušší způsob, jak provést drobnou změnu v dokumentaci, je využít odkazy na konci každé stránky:

- *Ukaž na GitHubu* otevře zdrojovou podobu dané stránky na GitHubu. Poté stačí stisknout tlačítko `E` a můžete začít editovat (je nutné být na GitHubu přihlášený)
- *Otevři náhled* otevře editor, kde rovnou vidíte i výslednou vizuální podobu

Protože [editor s náhledem |https://editor.nette.org/] nemá možnost ukládat změny přímo na GitHub, je nutné po dokončení úprav zdrojový text zkopírovat do schránky (tlačítkem *Copy to clipboard*) a poté jej vložit do editoru na GitHubu.
Pod editačním polem je formulář pro odeslání. Zde nezapomeňte stručně shrnout a vysvětlit důvod vaší úpravy. Po odeslání vznikne tzv. pull request (PR), který je možné dále editovat.


Větší úpravy
------------

Vhodnější, než využít rozhraní GitHubu, je být obeznámen se základy práce s verzovacím systémem Git. Pokud neovládáte práci s Gitem, můžete se podívat na průvodce [git - the simple guide |https://rogerdudler.github.io/git-guide/] a případně využít některého z mnoha [grafických klientů |https://git-scm.com/downloads/guis].

Dokumentaci upravujte tímto způsobem:

1) na GitHubu si vytvořte [fork |https://help.github.com/en/github/getting-started-with-github/fork-a-repo] repositáře [nette/docs |https://github.com/nette/docs]
2) tento repositář [naklonujete |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] na svůj počítač
3) poté v [příslušné větvi|#Struktura dokumentace] proveďte změny
4) zkontroluje přebytečné mezery v textu pomocí nástroje [Code-Checker |code-checker:]
4) změny uložte (commitněte)
6) pokud jste se změnami spokojeni, odešlete (pushněte) je na GitHub do vašeho forku
7) odtud je odešlete do repositáře `nette/docs` vytvořením [pull request|https://help.github.com/articles/creating-a-pull-request] (PR)

Je běžné, že budete dostávat komentáře s připomínkami. Sledujte navrhované změny a zapracujte je. Navrhované změny přidejte jako nové commity a znovu odešlete na GitHub. Nikdy nevytvářejte kvůli úpravě pull requestu nový pull request.


Struktura dokumentace
---------------------

Celá dokumentace je umístěna na GitHubu v repositáři [nette/docs |https://github.com/nette/docs]. Aktuální verze je v masteru, starší verze jsou umístěny ve větvích jako `doc-3.x`, `doc-2.x`.

Obsah každé větve se dělí do hlavních složek představujících jednotlivé oblasti dokumentace. Například `application/` odpovídá https://doc.nette.org/cs/application, `latte/` odpovídá https://latte.nette.org atd. Každá tato složka obsahuje podsložky představující jazykové mutace (`cs`, `en`, ...) a případně podsložku `files` s obrázky, které je možné do stránek v dokumentaci vkládat.

Jak přispět do dokumentace

Přispívání do dokumentace je jednou z nejpřínosnějších činností, neboť pomáháte druhým porozumět frameworku.

Jak psát?

Dokumentace je určena především lidem, kteří se s tématem seznamují. Proto by měla splňovat několik důležitých bodů:

  • Začněte od jednoduchého a obecného. K pokročilejším tématům přejděte až na konci
  • Snažte se věc co nejlépe vysvětlit. Zkuste například téma nejprve vysvětlit kolegovi
  • Uvádějte jen ty informace, které uživatel skutečně k danému tématu potřebuje vědět
  • Ověřte si, že vaše informace jsou skutečně pravdivé. Každý kód otestujte
  • Buďte struční – co napíšete, zkraťte na polovinu. A pak klidně ještě jednou
  • Šetřete zvýrazňovači všeho druhu, od tučného písma po rámečky jako .[note]
  • V kódech dodržujte Coding Standard

Osvojte si také syntax. Pro náhled článku během jeho psaní můžete použít editor s náhledem.

Jazykové mutace

Primárním jazykem je angličtina, vaše změny by tedy měly být v češtině i angličtině. Pokud angličtina není vaší silnou stránkou, použijte DeepL Translator a ostatní vám text zkontrolují.

Překlad do ostatních jazyků bude proveden automaticky po schválení a doladění vaší úpravy.

Triviální úpravy

Pro přispívání do dokumentace je nezbytné mít účet na GitHub.

Nejjednodušší způsob, jak provést drobnou změnu v dokumentaci, je využít odkazy na konci každé stránky:

  • Ukaž na GitHubu otevře zdrojovou podobu dané stránky na GitHubu. Poté stačí stisknout tlačítko E a můžete začít editovat (je nutné být na GitHubu přihlášený)
  • Otevři náhled otevře editor, kde rovnou vidíte i výslednou vizuální podobu

Protože editor s náhledem nemá možnost ukládat změny přímo na GitHub, je nutné po dokončení úprav zdrojový text zkopírovat do schránky (tlačítkem Copy to clipboard) a poté jej vložit do editoru na GitHubu. Pod editačním polem je formulář pro odeslání. Zde nezapomeňte stručně shrnout a vysvětlit důvod vaší úpravy. Po odeslání vznikne tzv. pull request (PR), který je možné dále editovat.

Větší úpravy

Vhodnější, než využít rozhraní GitHubu, je být obeznámen se základy práce s verzovacím systémem Git. Pokud neovládáte práci s Gitem, můžete se podívat na průvodce git – the simple guide a případně využít některého z mnoha grafických klientů.

Dokumentaci upravujte tímto způsobem:

  1. na GitHubu si vytvořte fork repositáře nette/docs
  2. tento repositář naklonujete na svůj počítač
  3. poté v příslušné větvi proveďte změny
  4. zkontroluje přebytečné mezery v textu pomocí nástroje Code-Checker
  5. změny uložte (commitněte)
  6. pokud jste se změnami spokojeni, odešlete (pushněte) je na GitHub do vašeho forku
  7. odtud je odešlete do repositáře nette/docs vytvořením pull request (PR)

Je běžné, že budete dostávat komentáře s připomínkami. Sledujte navrhované změny a zapracujte je. Navrhované změny přidejte jako nové commity a znovu odešlete na GitHub. Nikdy nevytvářejte kvůli úpravě pull requestu nový pull request.

Struktura dokumentace

Celá dokumentace je umístěna na GitHubu v repositáři nette/docs. Aktuální verze je v masteru, starší verze jsou umístěny ve větvích jako doc-3.x, doc-2.x.

Obsah každé větve se dělí do hlavních složek představujících jednotlivé oblasti dokumentace. Například application/ odpovídá https://doc.nette.org/cs/application, latte/ odpovídá https://latte.nette.org atd. Každá tato složka obsahuje podsložky představující jazykové mutace (cs, en, …) a případně podsložku files s obrázky, které je možné do stránek v dokumentaci vkládat.