#nettefw = #skvělá #dokumentace 📚 🙌

David Grudl

Nette má obsáhlou a dobrou dokumentaci. Unikátní bonus je, že ji má kompletně přeloženou i v češtině. Setkávám se s pozitivními reakcemi jak od začátečníků, tak od lidí, kteří pracují s jinými frameworky a mají možnost porovnávat.

(Samozřejmě úplně jiná záležitost jsou hejtři, kteří na první dobrou útočí proti dokumentaci, ale to není otázka kvalit dokumentace, jako spíš nenávisti v lidech.)

Ale chtěl bych, aby dokumentace nebyla jen dobrá, aby byla dokonalá. :-D

A tak jsem se pustil do dalekosáhlé revize. Kromě opravování chyb a aktualizací zastaralých informací, chci doplnit i všechny chybějící. A hlavně upravit text tak, aby byl maximálně srozumitelný, přesný, věcný a didaktický. Což je naprosto nejtěžší. Ufff…

Potřebuji k tomu zpětnou vazbu. Od zdatných programátorů, kteří dokáží odhalit chyby, nepřesnosti nebo omyly. Ale stejně tak od začátečníků, abych věděl, čemu neporozuměli, na čem se zasekli.

Protože dokumentace je opravdu obsáhlá, rozdělil jsem ji na několik etap, která mám zrevidované.

1. etapa

Tato etapa je zásadní, protože představuje všechny hlavní rysy frameworku. Jedná se o tyto kapitoly:

2. etapa

3. etapa

4. etapa

5. etapa

6. etapa Tester

Prosím, přečtěte si důkladně a pozorně tyto stránky, nemělo by to zabrat víc než deset-dvacet minut a třeba se i něco naučíte :) A napište mi k tomu věcný feedback.

Díky!

Budu rád taky za kontrolu anglických verzí

EncryptSL

@DavidGrudl Ahoj, podle dokumentace jsem poprvé začal psát jen tak lehký blog a zjistil že je to opravdu jednoduché. Díky vlastně všem článkům v dokumentaci jsem se naučil nette a také i seznámil s Latte, obkoukl i Github a hned jsem věděl.
Ze začátku to bylo trochu složitější jelikož jsem se bál do toho jít a učit se nette a věci kolem něj.

No a nakonec je to jednoduché z dokumentace vyčtu všechno potřebné. Ostatní jsem vždy hledal tu na foru. Hodně pomáhá Tracy bez ní bych už nic dělat nechtěl. Dokumentace je dle mého srozumitelná a obsahuje dostatek informací pro každého kdo začíná s nette nebo se sním chce seznámit. No změnilo mi to pohled na PHP dříve jsem se ho bál a vím že to byla chyba.

Jelikož jsem nezkoušel žádný jiný Framework než nette nemohu soudit dokumentace ostatních ale mohu říct že je tu to dobré a suprové.

Určitě pokračujte :) a vývoj nezastavujte, ať si každej kecá co chce za mě je to super, krok ale i dobrý Framework. Sorry :D ale jinak Feedback neumím dát jsem moc nadšený :D že tu je Nette a všechny doplňky k němu. A že to nemusím dělat :D a lámat na koleni :D.

sucho

Je to fajn ale možno by som prijal viac typov na riešenie možných problémov alebo ako veci obísť ak nastane problém

Ale možno by to bolo fajn aj ako blogy v časti Související články na blogu nejaké tie case studies
nap. typ pre presenter ako zmeniť layout pre ajaxové volania

vrana

Omlouvám se za offtopic (netýká se poptávané části, ale dokumentace obecně). Já měl problém hlavně se strohou API dokumentací. Např. v dokumentaci BaseControl jsou metody getControl(), getControlPart() a getControlPrototype(). Jaký je mezi nimi rozdíl? Proč jedna vrací Html|string, druhá Html|null a třetí Html? Z textového popisu těchto metod taky nejsem moudrý. Z API dokumentace by to chtělo stovky odkazů do té programátorské, hodně ukázek použití a podobně. Teď tam je jen jednořádkový popis (někdy ani ten ne) a signatura.

Za dobrou API dokumentaci považuji třeba tohle: https://cesium.com/…/Viewer.html
V popisu třídy ukázka použití, odkaz na demo, někde odkaz na články na blogu, podrobný popis metod a jejich parametrů, odkazy na související metody – s tím je radost pracovat.

V programátorské dokumentaci formulářů mi chyběla ukázka rozšíření DefaultFormRenderer, v API dokumentaci jsem žádnou ukázku taky nenašel.

David Grudl

Prosím, držme se těch etap…

(jinak API dokumentace se už bohužel vyvíjet nebude, nemám k tomu žádný nástroj.)

Michal Hlávka

Opravil jsem ve trech strankach typograficke chyby, application a presenters maji za me dost stejnej obsah, napriklad ohledne Latte sablon. Za me mi tam chybelo vice informaci o autowiringu. Kdy treba autowiring nastavit na false. Jinak dobry, na to ze jsem to sel typograficky zkontrolovat, abych mel co delat u kavy, jsem se i neco naucil :)

David Grudl

Michal Hlávka napsal(a):

Opravil jsem ve trech strankach typograficke chyby

díky

jkl

Jedna drobnost k části Konfigurace: chyběla mi (pokud jsem to nepřehlédl) tam zmínka, že se dají v neon configu použít environment variables pomocí např. ::getenv('DB_HOST')

Felix

David Grudl napsal(a):

(jinak API dokumentace se už bohužel vyvíjet nebude, nemám k tomu žádný nástroj.)

Hold me beer 🍺 ETA Q1/2021.

David Grudl

Připomínám se s prosbou o kontrolu prvních čtyř stránek dokumentace, ať můžu pokročit dál.

Věnujte tomu prosím těch pár minut, v nejhorším se něco přiučíte :-) Nebo jsou ty stránky snad dokonalé?

Václav Kraus

Mě to přijde dobré. Hlavně část Konfigurace.

Jen drobné rýpnutí.. V sekci Jak fungují Aplikace v části Adresářová struktura, tak je věta:
Na Linuxu nebo OS X nastavte adresářům log/ a temp/ práva pro zápis.

OS X už pár let neexistuje. Teď se to jmenuje macOS – https://cs.wikipedia.org/wiki/MacOS. Nevím, jestli je OS X nějak rozšířené označení, ale všichni, které znám, používají macOS :)

Mistrfilda

Ta tabulka s proklikem na stránce konfigurace je super :)

Jen pro mě je vlastně trochu nejasná tahle sekce https://doc.nette.org/…on/bootstrap#… nikdy jsem to takto nepoužil a všechny parametry definuju v configu, tipuji, že je to stejné ale možná by nebyla špatná zmínka, co je lepší používat? Popřípadě, že se tyto parametry dají definovat i přes neon?

Editoval Mistrfilda (22. 6. 2020 13:39)

David Grudl

Díky, opravil jsem OS X na macOS a zkusil trošku vylepšit ty parametry.

MajklNajt

@DavidGrudl v Jak fungují aplikace som si všimol, že si použil metódu __constructor namiesto __construct

EDIT: v Konfigurácií používaš %vendorDir%, ktorý sa nikde zatiaľ nespomínal, takže by som ho doplnil do Bootstrap medzi ostatné automaticky pridávané parametre.

Editoval MajklNajt (22. 6. 2020 17:20)

Toanir

Koukám na Jak fungují aplikace a třeba u vět:

„Nette totiž disponuje chytrou autodetekcí.“
„Šli byste jinak do značného bezpečnostního rizika.“

mi chybí vysvětlení / odkazy. Myslím že by bylo pěkný buď těmahle zvýrazněnýma pojmama odkázat na relevantní dokumentaci anebo u nich zobrazit bublinu se stručným vysvětlením při najetí myši / tapnutí.

U vysvětlování významu index.php mluvíme o bodu „získat továrnu“ kterej se ještě záměrně přeskakuje / foreshadowuje a přijde mi že to ani tak není vysvětlený jak by bylo potřeba. Myslím že bych to vypustil úplně a v tý sekci HTTP Požadavek zmínil že:

index inicializuje prostředí: konfiguráky, tracy, …
spouští aplikaci

a pak bych zmínil že „Jakže se získá Application? To je otázkou DI, které si zaslouží samostatnou kapitolu.“ anebo „O tom se dočtete později na této stránce“

V ostatních článcích jsem se dočetl samý rozumný věci a nevšiml jsem si ničeho, co bych měnil

David Grudl

Přidávám další dvě stránky, u kterých prosím o kontrolu:

2. etapa

PeckaDesign

U routování jsme bez podívání se do kódu nevěděli, v jakém pořadí se volají globální filtry a vlastní překladové funkce. Jestli nejdřív globální, potom pro každý atribut nebo obráceně. Volané pořadí dává smysl, akorát to není v dokumentaci.

Editoval PeckaDesign (25. 6. 2020 15:53)

David Grudl

Doplnil jsem.

MajklNajt

@DavidGrudl po prečítaní docky k Routovaniu mám guláš medzi servisami services: router vs services: application.router vs services: routing.router

Petr Parolek

Ahoj, takové možná rýpnutí do dokumentace, Nette je MVC framework, proč se tutoriál Píšeme první aplikaci! vůbec nedrží koncept MVC (MVP)? Model se míchá do kontroleru (presenteru) a o modelu se píše na závěr. Vyznívá mi to, jsako, že model je zbytečný nebo přežitý a že stačí mít VC (MP). Přijde mi to postavené na hlavu.

David Grudl

@ppar prosím držme se etap

savalo

Mozna by nebylo spatne do Konfigurace (sekce databaze) pridat odkaz na dibi konfiguraci ktera je take prelozena do en

Petr Parolek

ppar napsal(a):

Ahoj, takové možná rýpnutí do dokumentace, Nette je MVC framework, proč se tutoriál Píšeme první aplikaci! vůbec nedrží koncept MVC (MVP)? Model se míchá do kontroleru (presenteru) a o modelu se píše na závěr. Vyznívá mi to, jsako, že model je zbytečný nebo přežitý a že stačí mít VC (MP). Přijde mi to postavené na hlavu.

můžete mi objasnit lidi mínusy u mé věcné připomínky k tutoriálu?

joe

Tak jsem si zase přečetl dokumentaci :) a napíšu drobnosti, kterých jsem si všimnul. Je super, že vždycky když čtu tu „samou“ dokumentaci, vždycky se dozvím něco nového :D, díky. Pokud bude potřeba, mohu vytvořit PR.

Jak fungují aplikace?

„logování chyb“ → spíš „logované chyby“
„Trik je v tom n:href, které říká, že tento atribut zpracuje Nette. A vygeneruje:“ → je uvedena absolutní URL s protokolem a doménou, ale generuje se ve výchozím stavu bez protokolu a bez domény

Bootstrap

Hodilo by se uvést, že adresáře log a temp mají mít nastavená práva pro zápis
Statické parametry – bylo by dobré uvést nějaký praktický příklad, nenapadá mě v době čtení, k čemu bych to třeba použil
Importované služby – „vyjímečně“ → „výjimečně“

Presentery

v životním cyklu chybí afterRender
PHP doc /** @var ArticleRepository */ by šel už úplně vynechat a navádět k používání typů v PHP private ArticleRepository $articles;

Routování

„Jakékoliv závislosti, třeba na databázi atd, lze předávat do tovární metody jako její parametry:“ … tady bych to nechápal, hodil by se příklad s tím, jak by to pak vypadalo v Neonu
„Maska a parametry“ – Když jsem s Nette kdysi začínal, nedocházelo mi a ani teď to nemusí být úplně všem jasné, že parametry v routách <year> jsou vlastně ty přesně stejně pojmenované parametry metod int $year v akcích a že persistentní parametry se také jmenují podle stejného názvu. Možná to nedocházelo jenom mně :)

Editoval joe (5. 7. 2020 21:41)

David Grudl

Díky, zkusil jsem to zapracovat. Akorát PHP doc zatím používat musím, protože Nette 3.0 je pro PHP 7.1 a nechci to komplikovat.

Felix

V dokumentaci bychom mohli davat ukazky v posledni verzi php, nebo myslis, ze by v tom byl bordel?

David Grudl

Ukazky musí fungovat všem, ve verzi pro 2.4 taky nejsou skalární typehinty.

David Grudl

3. etapa

Mám tu pro vás desítku nových stránek:

Jde vesměs o přehledy API statických funkcí. Zajímá mě, jestli je všechno zcela srozumitelné.

I když je stránek deset, myslím, že přečtení víc než půl hodiny nezabere.

joe

Pole

v ukázce funkce every je v komentáři výsledek false, ale přitom má být true :)
(funkce get, možná už nevidím smysl využití, jednodušší mi přijde $value = $array['foo'] ?? 'bar')

Datum a čas

„tímezone“

Souborový systém

Zapíše „řetezec“ – „ě“

Finder

(návrh) u metod size a date bych možná čekal nějaký alias v podobě metod místo psaní jednoduché metory s operátory (protože si je musím dohledávat) ->sizeGreatherThan(100). Případně jaké ty operátory mohu všechny napsat? Třeba jsem to někde přehlédnul.

Řetězce

metoda compare – „a pokud je argument roven nule, porovnávají se celé řetězce.“. A pokud je null, tak co? :)

Zase jsem se dozvěděl pár nových věcí, co se mi budou hodit. Při čtení signatur metod mi celkem vadilo, že typy parametrů splývají s parametry, odlišil bych to možná místo kurzívy spíš šedou barvou, pak parametry víc vyniknou a nebude je potřeba pak hledat u metod, kde těch parametrů je víc.

David Grudl

Všem, co přečetli stránky dokumentace, děkuji za připomínky, ať už tady nebo na facebooku!

A prosím další z vás: PŘEČTĚTE SI TO :-)

Nezabere to vůbec tolik času, něco se dozvíte a pomůžete všem ostatním, co budou v budoucnu dokumentaci studovat.

David Grudl

4. etapa

Dalších 13. přepsaných nebo nově doplněných stránek je tu ke korektuře!

Andy3

Ahoj, u toho RobotLoaderu mi chybi informace, ze o toto se muze postarat i Composer, pokud se dodrzuje PSR-4. Ukazka jak ho vypnout a nechat praci udelat Composer. Novacci nemusi vedet, ze existuje nejake PSR.

„nevyžaduje se žádná striktní konvence pojmenování souborů“ Tohle je otazka, jestli je plus nebo minus. Ono to na druhou stranu toleruje preklepy a nikdy bych nerekl kolik jsme jich v aplikaci meli, nez jsme ho vypli.

Nerikam RobotLoader smazat a zahodit, urcite ma sve misto, ale by bylo hezke, aby si programator po precteni docu uvedomoval plusy a minusy obojiho.

Editoval Andy3 (21. 7. 2020 7:37)

Pavel Janda

@Andy3 naprosto s tebou souhlasím. Možná bych uvedl, že je RobotLoader super například pro legacy kód, který se bude jinak autoloadovat jen stěží.

Já osobně bych rád odstranil RobotLoader ze sandboxu a web-projectu, ale to už je jiné téma. Jinak RobotLoader používám právě pokud řeším legacy code base, na to je superskvělej. 👍

David Grudl

5. etapa

Další kapitoly ke korektuře! Tentokrát na psaní složitější témata, takže zpětná reakce je o to důležitější.

Petr Parolek

https://doc.nette.org/cs/caching#… tady mi vvůbec není jasné, jak vypíšu data? Přes echo "text foo";?

Intapps

Mně v kapitole Překládání chybí konkrétní příklady, jako jsou třeba v kapitole Přihlašování.
Nedokážu z toho pochopit, jak bych měl konkrétně vytvořit překladač třeba pro ten formulář.

Petr Parolek

Ahoj, postupuju podle doc https://doc.nette.org/cs/mail#… , ale řve na mě, že nezná filtr pro překlady LogicException Filter 'translate' is not defined, did you mean 'truncate'?. Používám https://github.com/…/translation . Kde je prosím zrada?

Petr Parolek

Ahoj, není v rozporu kod https://github.com/…s/Arrays.php#L105 s dokumentací ? V doc https://doc.nette.org/cs/utils/arrays#… se píše, že key může být null. „Vloží obsah pole $inserted do pole $array hned za prvek s klíčem $key. Pokud klíč v poli není, vkládá se na konec.“ @DavidGrudl

Petr Parolek

https://web.archive.org/….org/cs/mail#… starý způsob funguje.

Je možné, že vymyslel potom @davidgrudl nějakou novou magii, která nefunguje vždy. Kod jsem zkusil a mail odešel, jak má.

David Grudl

6. etapa Nette Tester

Vždycky jsem označoval Tester za triviální testovací nástroj a dokumentace má osm stran :-) A těší se na vaše připomínky.

Václav Pávek

Proletěl jsem a za mě super, hned jsem předal do teamu. Kromě Průběžné testování s Travis CI by nebylo špatné tam mít Průběžné testování s GitLab CI 😉

David Grudl napsal(a):

6. etapa Nette Tester

Začínáme s Nette Tester

Psaní testů

Spouštění testů

Aserce

Anotace testů

TestCase

Pomocné třídy

Průběžné testování s Travis CI

Vždycky jsem označoval Tester za triviální testovací nástroj a dokumentace má osm stran :-) A těší se na vaše připomínky.

CZechBoY

gitlab ci/circle ci/github ci/travis ci… opravdu si myslis ze ma smysl psat ty 3 radky tolikrat?

btw mozna bych zvazil vymenu Travis CI za github actions

Felix

CZechBoY napsal(a):

gitlab ci/circle ci/github ci/travis ci… opravdu si myslis ze ma smysl psat ty 3 radky tolikrat?

btw mozna bych zvazil vymenu Travis CI za github actions

Za bych tam klidne dal nejcastejsi CI sluzby (Travis, Circle, Gitlab Pipelines, Github Actions). 90% informaci muze byt obecnych a pak se to bude lisit jenom v tech konfiguracich.

David Grudl

A můžete to prosím sepsat, kdo ty služby používáte?

dakur

Na stránce „Začínáme“ jsou uvedené možné stavy toho, jak test skončí. Nevěděl jsem ovšem, co znamená, že je test přeskočen (skipped). Tak jsem hledal pomocí Ctrl+F tam a ještě v kapitole Spouštění testů a nenašel. Až pak jsem náhodou při dalším čtení narazil na nadpis „Anotace a přeskakování testů“ v kapitole „Psaní testů“. Navrhuju na to dát ze „Začínáme“ i z „Spouštění testů“ odkaz.

Editoval dakur (6. 10. 2020 17:13)