Dokumentace na GITu a co dál?

Upozornění: Tohle vlákno je hodně staré a informace nemusí být platné pro současné Nette.
David Grudl
Nette Core | 8074
+
0
-

Přesně od TEĎ je dokumentace a vůbec veškerý obsah těchto stránek finálně na GITu https://github.com/nette/docs.

Hurá!

A co to přesně znamená? Znamená to, že od nynějška bude editování stránek výrazně komplikovanější :-) Oprava každé chybky bude vyžadovat vytvořit pull request, bez možnosti náhledu syntaxe, atd. Ale vzhledem k tomu, že jen minimum lidí dokumentaci vylepšovalo, vadit to nemusí. Výhodou je, že pro správu můžeme využívat plnou sílu Gitu a především podporu větvení dokumentace podle verzí.

Což si vyzkoušíme ihned, protože vydání příští verze je zrovna na pořadu dne. (Vyjde ve chvíli, kdy bude hotová dokumentace.)

Ještě před vytvořením doc-dev bude záhodno projít a uzavřít současnou dev-2.0. Na poslední Poslední sobotě jsme si rozdělili zodpovědnosti za témata:

Ideální je, aby každé téma měli pod palcem dva lidé a mohli si dělal navzájem korekturu a oponenturu, proto bude super, pokud se k některému z uvedených (a nebo opomenutých) témat přihlásíte!

Nejprve je tedy potřeba obsah stránek projít, aby tam nebyly chyby, nesmysly, nechyběly zásadní informace atd. Bylo by dobré přihlédnout k obsahu komentářů pod články a podle nich opravit nedostatky. A taktéž komentáře promazat.

Primárním jazykem se stává angličtina. První vlaštovnou, která je pouze v angličtině a v češtině chybí, je nový quick start. U všeho ostatního musíme zajistit, aby si obě jazykové verze odpovídali. Nikdo z nás snad krom Juzny nedokáže psát anglicky gramaticky správně, ale to absolutně nevadí. Vůbec.

Pochopitelně během procházení člověk narazí na věci, které by už rovnou upravoval pro novou verzi Nette. To není problém, lze si vytvořit lokální větev doc-dev a potom se to jen cherry-pickne do oficiální.

Takový je tedy plán!

(Addons v repozitáři nejsou, protože pro ně spustíme zcela nový web).

hrach
Člen | 1834
+
0
-

Mohl bych poprosit o blizsi vysvetleni, co je „projít a uzavřít současnou dev-2.0“. Např. u dabatase bych to celý smazal, to je jediný zodpovědný přístup, protože jsou tam i bludy :D

pave.kucera
Člen | 122
+
0
-

S radostí bych oponoval Honzovi Tvrdíkovi.

buffus
Člen | 101
+
0
-

@ David Grudl: …a co dál? Jen takový námět: Osobně bych velmi ocenil, kdyby na stránce https://doc.nette.org/ existovala alternativa „Dokumentace Nette na jedné webové stránce“, něco jako mají na
http://www.gnu.org/…tils/manual/
konkrétně
HTML (1352K bytes) – entirely on one web page
http://www.gnu.org/…reutils.html

Kolikrát pořádně ani nevím co hledám, ale pamatuji si jen nějaký útržek kódu nebo textu, tak pomocí prostého Ctrl-f (např. v Chrome) se mi scroll-bar prohlížeče obarví hustě v místech největšího počtu výskytů hledaného.

Většinou v takových „entirely on one web page“ manuálech najdu opticky rychleji co hledám, než místo těžkopádnějšího pročítání výsledků vyhledávače. Naincludovat jednotlivé části aktuální dokumentace do jedné stránky by myslím neměl být problém… Tak jen takový námět.

petr.pavel
Člen | 533
+
0
-

@buffus: +1

Párkrát se mi stalo, že jsem hledal něco, co je z podstaty věci rozptýleno po víc stránkách. Taky možná, že jsem několikrát hledal tu samou věc :-)

rixi
Člen | 109
+
0
-

@buffus: +1

Honza Kuchař
Člen | 1662
+
0
-

…a jak se teď edituje dokumentace doplňků? Nemohu najít ty správné soubory na githubu… :-/

webdata
Člen | 153
+
0
-

buffus napsal(a):

@ David Grudl: …a co dál? Jen takový námět: Osobně bych velmi ocenil, kdyby na stránce https://doc.nette.org/ existovala alternativa „Dokumentace Nette na jedné webové stránce“, něco jako mají na
http://www.gnu.org/…tils/manual/
konkrétně
HTML (1352K bytes) – entirely on one web page
http://www.gnu.org/…reutils.html

Kolikrát pořádně ani nevím co hledám, ale pamatuji si jen nějaký útržek kódu nebo textu, tak pomocí prostého Ctrl-f (např. v Chrome) se mi scroll-bar prohlížeče obarví hustě v místech největšího počtu výskytů hledaného.

Většinou v takových „entirely on one web page“ manuálech najdu opticky rychleji co hledám, než místo těžkopádnějšího pročítání výsledků vyhledávače. Naincludovat jednotlivé části aktuální dokumentace do jedné stránky by myslím neměl být problém… Tak jen takový námět.

Jestli stačí tohle? http://goo.gl/bpOj7Q

buffus
Člen | 101
+
0
-

@webdata: Bomba! Díky. Šlo by to vyexportovat i jako jeden HTML soubor?

Majkl578
Moderator | 1364
+
0
-

@webdata: Smíme znát i nástroj, kterým jsi to vyexportoval? Mohlo by pomoci s https://github.com/…cs/issues/44.

romiix.org
Člen | 343
+
0
-

webdata napsal(a):
Jestli stačí tohle? http://goo.gl/bpOj7Q

Super! Kto by povedal, že je toho 147 strán. A že Nette nemá dokumentáciu :)

webdata
Člen | 153
+
0
-

buffus napsal(a):

@webdata: Bomba! Díky. Šlo by to vyexportovat i jako jeden HTML soubor?

Ano půjde to, ale s obrázky to bude kapének velký. Momentálně teď není čas, ale o víkendu bych něco spáchal. A ještě bych tam musel nějak vychytat provazaní pres odkazy. Coz třeba v tom PDF neni.

Majkl578 napsal(a):

@webdata: Smíme znát i nástroj, kterým jsi to vyexportoval? Mohlo by pomoci s https://github.com/…cs/issues/44.

No je to cca 100 řadku kodu. Žádnej zázrak. Prostě jsem stahnul dokumentaci s git. Z homepage.texy vytahal kapitoly. Sestavil z toho jedno velke HTML a to prevedl pomoci programu HTMLToPDF do PDF (je to free verze).

Edit – jinak zde jsou ještě starší verze, které jsem nějak nevypouštěl:

http://uloz.to/…ramatora-pdf
http://uloz.to/…ramatora-pdf

Editoval webdata (30. 1. 2014 0:02)

Patrik Votoček
Člen | 2221
+
0
-

A hodíl by jsi těch 100 řádků třeba na github?

Editoval Patrik Votoček (30. 1. 2014 1:55)

webdata
Člen | 153
+
0
-

Patrik Votoček napsal(a):

A hodíl by jsi těch 100 řádků třeba na github?

No nevim kod je tak prasackej ze nevim nevim :-)

Až bude čas tak plánuji udělt lepší generator, kde budou stránky, obsah a možnost na papir, tak aby nebyl kus na jedne strance a kus na strance druhe.

Tenhle můj pokus je jen nouzovka a praktikuji to třetim rokem. Tak že mám vždy na jeden rok jednu tištěnou podobu, ve které si před spaním čtu.

Editoval webdata (30. 1. 2014 2:18)

webdata
Člen | 153
+
0
-

Zde je verze v jednom HTML vcetne obrazku:

http://goo.gl/50DWXR

Po rozbaleni má ten HTML cca 5.5Mb

Jo jinak si stema PDF a HTML muzete delat co chcete. Dal to sirte. Davejte na to odkazy. Uploadnite to kam chcete, ale nekde tam nechte zminku ze jsem to konvertoval ja.

Editoval webdata (30. 1. 2014 3:03)

honos
Člen | 109
+
0
-

webdata napsal(a):

Zde je verze v jednom HTML vcetne obrazku:

http://goo.gl/50DWXR

Po rozbaleni má ten HTML cca 5.5Mb

Jo jinak si stema PDF a HTML muzete delat co chcete. Dal to sirte. Davejte na to odkazy. Uploadnite to kam chcete, ale nekde tam nechte zminku ze jsem to konvertoval ja.

To je pdf kamarade, ale je udelana pekne.

EDIT: Teda pardon. To byl tento odkaz

Editoval honos (30. 1. 2014 8:02)

buffus
Člen | 101
+
0
-

webdata napsal(a):

Zde je verze v jednom HTML vcetne obrazku:

http://goo.gl/50DWXR

To je přesně ono. Děkuju!

vojtaBelovsky
Člen | 1
+
0
-

webdata: diky moc!!

Vubec by nebylo marne dat to PDFko primo na stranku s dokumentaci ;-)

Editoval vojtaBelovsky (24. 3. 2014 6:02)

Tomáš Votruba
Moderator | 1114
+
+1
-

Pro online potřeby jsem nahrál html verzi k sobě