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

před 2 měsíci

David Grudl
Nette Core | 7148
+
+18
-

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


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í

před 2 měsíci

EncryptSL
Člen | 6
+
+6
-

@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.

před 2 měsíci

sucho
Člen | 57
+
+1
-

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

před 2 měsíci

vrana
Člen | 132
+
+8
-

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.

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

před 2 měsíci

David Grudl
Nette Core | 7148
+
0
-

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.)

před 2 měsíci

Michal Hlávka
Člen | 191
+
0
-

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 :)

před 2 měsíci

David Grudl
Nette Core | 7148
+
0
-

Michal Hlávka napsal(a):

Opravil jsem ve trech strankach typograficke chyby

díky

před 2 měsíci

jkl
Člen | 5
+
0
-

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')

před 2 měsíci

Felix
Nette Core | 1034
+
+3
-

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.

před 2 měsíci

David Grudl
Nette Core | 7148
+
0
-

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é?

před 2 měsíci

Václav Kraus
Backer | 59
+
0
-

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 :)

před 2 měsíci

Mistrfilda
Backer | 62
+
+1
-

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

Jen pro mě je vlastně trochu nejasná tahle sekce https://doc.nette.org/….0/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. 13:39)

před 2 měsíci

David Grudl
Nette Core | 7148
+
+2
-

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

před 2 měsíci

MajklNajt
Člen | 358
+
0
-

@DavidGrudlJak 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. 17:20)

před 2 měsíci

Toanir
Člen | 51
+
0
-

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

před 2 měsíci

David Grudl
Nette Core | 7148
+
+2
-

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

2. etapa

před 2 měsíci

PeckaDesign
Gold Partner | 2
+
0
-

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. 15:53)

před 2 měsíci

David Grudl
Nette Core | 7148
+
0
-

Doplnil jsem.

před 2 měsíci

MajklNajt
Člen | 358
+
0
-

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

před 2 měsíci

ppar
Backer | 334
+
-7
-

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.

před 2 měsíci

David Grudl
Nette Core | 7148
+
0
-

@ppar prosím držme se etap

před měsícem

savalo
Člen | 3
+
0
-

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

před měsícem

ppar
Backer | 334
+
0
-

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?

před měsícem

joe
Člen | 277
+
+2
-

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. 21:41)

před měsícem

David Grudl
Nette Core | 7148
+
+2
-

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.

před měsícem

Felix
Nette Core | 1034
+
0
-

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

před měsícem

David Grudl
Nette Core | 7148
+
0
-

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

před měsícem

David Grudl
Nette Core | 7148
+
+1
-

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.

před měsícem

joe
Člen | 277
+
+1
-

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.

před 26 dny

David Grudl
Nette Core | 7148
+
0
-

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.

před 25 dny

David Grudl
Nette Core | 7148
+
+2
-

4. etapa

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

před 20 dny

Andy3
Backer | 15
+
+3
-

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. 7:37)

před 20 dny

Pavel Janda
Backer | 914
+
+2
-

@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. 👍

před 12 dny

David Grudl
Nette Core | 7148
+
+1
-

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ší.

před 12 dny

ppar
Backer | 334
+
0
-

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

před 12 dny

Intapps
Člen | 3
+
0
-

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ář.

před 9 dny

ppar
Backer | 334
+
-2
-

Ahoj, postupuju podle doc https://doc.nette.org/cs/3.0/mailing#… , 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?

před 9 dny

ppar
Backer | 334
+
0
-

Ahoj, není v rozporu kod https://github.com/…s/Arrays.php#L105 s dokumentací ? V doc https://doc.nette.org/cs/3.0/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

před 9 dny

ppar
Backer | 334
+
0
-

https://web.archive.org/…/3.0/mailing#… 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á.

před 9 dny

David Grudl
Nette Core | 7148
+
0
-

Používám https://github.com/…/translation . Kde je prosím zrada?

Co to znamená „používám“? Jak ho přesně používáš?

https://doc.nette.org/cs/3.0/arrays… se píše, že key může být null.

To nemůže najít. Kde přesně se píše, že může být null?

před 8 dny

ppar
Backer | 334
+
0
-

ppar napsal(a):

Ahoj, postupuju podle doc https://doc.nette.org/cs/3.0/mailing#… , 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?

Dotaz na lidi, kteří dali minus – vám kod funguje, jak má?

před 8 dny

chemix
Gold Partner | 1146
+
0
-

Ahoj @ppar a definoval jsi tam ten filtr, jak ti radi Tracy ? mozna ukaz ukazku, jak s tim pracujes at je videt kde je problem …

před 8 dny

ppar
Backer | 334
+
-1
-

ento filtr je přece defaultně v Nette! Nebo se mají nějak taky instalovat jako tagy n:href atd.?

před 8 dny

David Grudl
Nette Core | 7148
+
0
-

Ten filtr tam defaultně není. Protože není žádný defaultní translator. Ty jsi psal že používáš contributte, jiní používají jiné knihovny atd. Žádný default neexistuje.

V předchozím řešení to nicméně fungovalo, protože kopírovalo nastavení šablony z prezenterů. To novější je víc low level, takže tam to automaticky nefunguje. Zkrátka objekt, který vytvoříš, nemůže tušit, že něco používáš.

před 7 dny

ppar
Backer | 334
+
0
-

@DavidGrudl vím, ale nenapadá mě řešení.