ApiGen: tipy na vylepšení homepage
- David Grudl
- Nette Core | 8249
Vypadalo to, že ApiGen umřel, takže jsem rád, že @TomášVotruba pokračuje dále ve vývoji. Měl bych pár poznámek k vylepšení zejména homepage. Píšu to sem, protože ApiGen vnímám jako projekt úzce související s Nette a nechci (zatím) otevírat několik issue, protože jde spíš o úvahy.
Instalace
Je super, že ApiGen opustil PEAR, díky tomu jej můžu dropnout i u Texy. Nicméně instalace pomocí
$ curl -sS http://apigen.org/installer | php
je stále příliš složitá, neboť nefunguje na Windows, kde curl
standardně není. Není jednodušší nabídnout přímo
apigen.pear
ke stažení? Tak jak je v releases?
Instalace „Using Composer as dependency of your project“ a stejně tak
„Using Composer globally“ jsou fundamentálně špatně. Existuje jen jeden
jediný způsob, jak instalovat ApiGen pomocí Composeru, a tím je příkaz
composer create-project
, neboť ApiGen je projekt, nikoliv
knihovna.
Homepage
Když už jsme u instalace, na homepage chybí viditelné tlačítko „Download ApiGen“ v horní části stránky, které stáhne aktuální phar. Odkazovat kvůli instalaci na GitHub je IMHO jen překážkou navíc, nehledě na to, že odkaz je umístěn až pod ohybem.
Odkaz „Take a look at an example.“ je nevyužitá příležitost. ApiGen má dnes reference, kterými se může (MUSÍ!) pochlubit:
- Amazon Web Services
- Doctrine
- CakePHP (teď už bohužel přebrandovaný na CakePHP API Docs…)
- a určitě další
Tohle je potřeba prodat.
Zároveň @juzna.cz kdysi vytvořil online generátor dokumentace na http://apigen.juzna.cz – nevím, jestli to ještě funguje, ale pokud ano, je třeba to propagovat na čelním místě stránky: „Vyzkoušejte si ApiGen na svém projektu!“
Features
Fakt nikoho nezajímá, že „Our own TokenReflection library is used“, už vůbec ne jako bod č. 1. Informace o použitých knihovnách, ať už jde o TokenReflection, Nette nebo Latte, bych ponechal v patičce. Uživatelům je to šumák.
Co je skutečná přednost ApiGenu? Čím se liší od jiných systémů? Když jsem psal první verzi, tak z mého pohledu ta killer feature byla
- Přehlednost (tohle byl standard phpDocumentor, tohle byl ApiGen).
- Podpora nových vlastností PHP
- Rychlost (2 minuty phpDocumentor versus 11 sekund ApiGen)
Netuším, jak je dnes na tom phpDoc nebo jiné systémy, rychlost možná už nehraje žádnou roli, ale přehlednost je stále výhoda, kterou se dá odlišit od konkurence a na kterou člověk uslyší. Kdo nechce mít přehlednou dokumentaci?
Přitom není ve výčtu vlastností vůbec uvedena.
Klidně bych nahradil titulek „API documentation generator for PHP“ za „Chcete přehlednou dokumentaci?“
- Honza Marek
- Člen | 1664
Instalace „Using Composer as dependency of your project“ a stejně tak „Using Composer globally“ jsou fundamentálně špatně. Existuje jen jeden jediný způsob, jak instalovat ApiGen pomocí Composeru, a tím je příkaz composer create-project, neboť ApiGen je projekt, nikoliv knihovna.
Tomu moc nerozumim, obě metody mi přijdou OK. Apigen je podobný dev nástroj jako třeba phpunit, který se běžně oběma způsobama instaluje.
Pravda je, že composer narozdíl od npm neumožní každé knihovně requirovat vlastní verze závislostí, tak by mohl apigen způsobovat konflikty verzí, ale filozoficky v instalaci pomocí composeru problém nevidim.
- Tomáš Votruba
- Moderator | 1114
@DavidGrudl Díky za nápady. Já se teď věnuji převážně refaktoringu a testům, takže jsou velmi vítány.
S úpravami stránek a marketingu souhlasím ve všech bodech.
Jen pár poznámek:
Stránky
Na stránce jsem začal dělat, nicméně @kukulich je revertnul bez dalšího vysvětlení, tak jsem dál nepokračoval.
Osobně bych byl pro udržování readme.md
v github repu a
redirect apigen.org
. Je to mnohem jednodušší: poslání PR vs
získání FTP účtu, udržování 2 zdrojů a další. 2 roky vytuhnutí
obou zdrojí a tvé připomínky mluví pro.
Bylo by fajn mít udržované a aktuální stránky, ale za rok budou zase zastaralé a mást uživatele, jako teď matou tebe. Tolik k mým obavám.
Instalace
Neměl jsem v tom příliš jasno, tak jsem vydal v září anketu. Na odpovědi můžeš kouknout tu: https://github.com/…n/issues/159#…
Composer
a composer --global
padaly v issues jako
žádané možnosti (když jsem rozbil kompatibilitu :)). ApiGen vidím podobně
jako PhpCodeSniffer, lze použít jako projekt i jako knihovnu.
Nicméně toto bych řešil až po všem ostatním, co píšeš, jelikož to jediné zasahuje i do kódu, a přehledná a úspěšná instalace je teď mnohem důležitější.
Jo a generátor od @juzna.cz bohužel už cca půlroku nefunguje.
Editoval Tomáš Votruba (10. 11. 2014 15:19)
- David Grudl
- Nette Core | 8249
Tady alespoň vidíš nesmyslnost anket při vývoji open source :-)
ad composer a composer global
Instalovat ApiGen jako součást projektu je úplně totéž, jako když
donutíš dva vývojáře, co se ani neznají a pracují na úplně jiném
projektů, aby sdíleli společnou složku vendor
. Na to se dá
říct „proboha proč by to měli dělat?“ a „vždyť to přece
nemůže fungovat.“ Nemůže.
Rozdíl mezi composer a composer global je jen v tom, že nepůjde o dva cizí vývojáře ale o deset cizích vývojářů. Tedy je to nesmysl na druhou.
Tedy composer global
je špatné řešení úplně vždy, při
jakýchkoliv use cases. Lokální composer je špatné řešení pro instalaci
projektů, jako je Sandbox, ApiGen nebo CodeChecker.
Třeba takový Tester se pomocí composeru instaluje lokálně, protože jeho součástí je i framework. Zároveň to ale znamená, že spouštěč testů nemůže mít žádné obecné závislosti. Jinak by se musel oddělit.
Takže ApiGen stejně jako Nette Sandbox lze instalovat jen a pouze pomocí
composer create-project
. Jinak se dříve nebo později utopíš
v záplavě issues kvůli kolizi verzí, na které nebude rady.
Ten http://apigenerator.org/ vypadá dobře!
- David Grudl
- Nette Core | 8249
Honza Marek napsal(a):
Pravda je, že composer narozdíl od npm neumožní každé knihovně requirovat vlastní verze závislostí, tak by mohl apigen způsobovat konflikty verzí, ale filozoficky v instalaci pomocí composeru problém nevidim.
To je právě to klíčové. Proto jsou globální instalace přes npm velmi užitečné, zatímco přes Composer nemožné. V npm má každý projekt i každá knihovna svou vlastní složku vendor (resp. node_modules).
- Jan Tvrdík
- Nette guru | 2595
@TomášVotruba Proč se vlastně ve verzi 4.0 měnilo CLI? Bylo s tím starým něco špatně?
- Pavel Macháň
- Člen | 282
Btw co ten ApiGen přesunout také pod nette web (jako to má tester a tracy)? Nebude nutné dělat nový web a ještě je šance, že přijde do podvědomí(v zahraničí) i nette a ostatní :)
Editoval Pavel Macháň (10. 11. 2014 18:57)
- David Grudl
- Nette Core | 8249
V samostatném webu vidím velkou výhodu. Že se něco duplikuje s GitHubem nevadí, obsah se nemění až tak často a readme na GitHubu má velmi omezené možnosti, jak upoutat pozornost.
Web může být přímo hostován na GitHubu, aktualizován pomocí pull requestů, podobně jako php-fg, stačí změnit DNS záznam u domény.
- Tomáš Votruba
- Moderator | 1114
@tmysik, @JanTvrdik: Na tohle pouzivejte issues. CLI planuji pridat pred 4.0.
@DavidGrudl: Diky za rozbor, jeste v tom OS plavu.
Stranky na githubu a DNS zni skvele. Vezmes si to na starost?
- kukulich
- Člen | 58
@Andrewsville bohužel ApiGen opustil před více než rokem.
Já jsem sice měl snahu ApiGen vyvíjet dále, ale prostě jsem to nedal, i když jsem se snažil. Po narození syna se mi hodně proházely priority. Navíc mám hodně práce ve Slevomatu. A vyvíjet bez @Andrewsville kromě ApiGenu ještě TokenReflection a FSHL, bez kterých ApiGen nebude fungovat, je prostě teď na mě moc.
Jsem tedy hrozně rád, že @TomášVotruba ApiGen zase posouvá dál a dodělal refactoring, který jsem pouze rozdělal.
Rozhodně souhlasím s tím, že web je třeba upravit. Readme na GitHubu ho ale opravdu nenahradí.
Web už má repozitář, takže klidně posílejte pull requesty. Vývoj samotného ApiGenu teď nedávám, ale rád se budu aktuálně podílet aspoň na správě webu.
Na ApiGenu jsem strávil hodně času, takže úplně opouštět se mi ho nechce. A ještě jednou děkuji @TomášVotruba, že se ho ujal!
- Tomáš Votruba
- Moderator | 1114
@kukulich Díky, je to pro mě velká čest a zkušenost, pracovat na ApiGenu.
Můj syn mě čeká za měsíc a repo se pomalu blíží k trvalé udržitelnosti i při dětech (doufám :)).
Díky za pomoc se správou webu, spolu s PR (pull-requesty) a PR (public relations) od @DavidGrudl to myslím půjde.