phpDocumentor 2 místo DocBloxu

bakalářce jsem popisoval rozhodování mezi různými nástroji na generování PHP API dokumentace v rámci kontinuální integrace. Teď se výběr zjednodušil, proto z nástroje DocBlox se stal se phpDocumentor 2. Sice se v článku mluví o „merge“, ale ve skutečnosti jde o přejmenování s tím, že původní phpDocumentor se přestane vyvíjet.

Nainstalovat ho můžeme pomocí:

pear channel-discover pear.phpdoc.org
pear install phpdoc/phpDocumentor-alpha

Kromě výchozí šablony jsou k dispozici i nějaké další, ale nešly mi doinstalovat starým postupem tak jako u DocBloxu, ale musel jsem přes PEAR:

pear install phpdoc/phpDocumentor_Template_checkstyle
pear install phpdoc/phpDocumentor_Template_zend

Přehled všech dostupných šablon najdete na http://pear.phpdoc.org/

Generování funguje pořád stejně, jen je potřeba vyměnit docblox za phpdoc:

phpdoc -f phpdoc01.php
phpdoc -f phpdoc01.php --template checkstyle

Na výchozí šabloně mě překvapilo, že v detailu třídy nikde není vypsané její jméno. Holt je to ještě alpha.

Až bude phpDocumentor 2 stabilní, tak určitě bude dobré znovu zvážit výběr nástroje na generování API dokumentace. Přechod z DocBloxu je jasný, ale pokud se objeví i šablona podobná té v ApiGenu, tak bych kvůli cachování analyzovaných souborů (zrychlení oceníte hlavně u větších projektů) zvážil přechod na phpDocumentor.

Čím generujte API dokumentaci v PHP vy?

PHP_CodeBrowser 1.0.3 a změna PEAR kanálu

Pro reportování chyb z PHP_CodeSniffer, PHPCPD a PMD jsem při nasazení kontinuální integrace použil PHP_CodeBrowser. Nicméně, nelíbilo se mi, že jsou v reportu vypsané i soubory, které žádné chyby neobsahují – pak se hůře hledají ty, ve kterých chyby jsou.

Doprogramoval jsem tedy možnost takové soubory skrýt.

--excludeOK    Exclude files with no issues from the report

Před pár dny vyšla verze 1.0.3, která už vylepšení obsahuje. Zároveň došlo ke změně PEAR kanálu pro instalaci balíčku.

Pro upgrade je tedy potřeba starou verzi nejdříve odinstalovat:

pear uninstall phpunit/PHP_CodeBrowser

Pak přidat nový kanál a nainstalovat PHP_CodeBrowser z něj:

pear channel-discover pear.phpqatools.org
pear install phpqatools/PHP_CodeBrowser

A do build skriptu stačí přidat přepínač --excludeOK, takže příkaz pro generování pomocí phpcb bude vypadat takto:

phpcb  --log ${project.basedir}/build --source ${project.basedir} --output ${project.basedir}/build/code-browser --excludeOK

Používáte také PHP_CodeBrowser nebo si v Jenkinsu vystačíte s Violations?

Kontinuální integrace při vývoji webových aplikací v PHP (bakalářská práce)

Když jsem si vybíral téma na bakalářskou práci, tak jsem chtěl zpracovat něco, co bude užitečné a někdo si to přečte, protože ho to bude zajímat. Nakonec jsem si vybral Continuous Integration (neboli hezky česky Kontinuální integraci).

Myslím, že se mi to povedlo a práce je užitečná a i docela čtivá. //jo, je to sebechvála ;)

Vzhledem k tomu, že mám obhajobu až v červnu, tak ještě nemám posudky, tudíž není akademicky posvěcená. Věci kolem kontinuální integrace se pořád mění, tak mi přijde škoda ji nechat dva měsíce zbytečně zastarávat.

Zároveň vzhledem k tomu, že u BP není zvykem vydávat aktualizované verze, plánuju tu a tam napsat na blog o různých novinkách, které kolem CI vyzkouším (takže sledujte blog, případně Twitter)

Kontinuální integrace při vývoji webových aplikací v PHP (Bakalářská práce)

Ke stažení ve formátu PDF

Co na ni říkáte? Pokud vám pomůže s nasazením kontinuální integrace na váš projekt, tak budu rád, když mi napíšete do komentářů nebo na e-mail.

Moje články o kontinuální integraci:

Integrating JavaScript/Node.js projects with JSHint, Mocha and Jenkins [EN]

I've set up the Continuous Integration for PHP projects on Jenkins recently. It went quite well, but the fact that CI tools for PHP are not as mature as those for Java was obvious. (Most of the PHP CI tools are ports of their Java originals.)

Apart from PHP projects, my colleague just started working on a new project, using JavaScript and Node.js, so I thought it would be nice to add it to Jenkins too.

After some experiments, I came to this:

  • Java: It is normal to use CI in Java world.
  • PHP: QA and CI are being adapted in PHP world.
  • JavaScript: Very few people are using CI. Lots of WTF.

However, I was able to create a basic setup with Mocha for unit testing and JSHint for static analysis. Here is how I did it:

JavaScript environment

First, I wanted to add JS environment to the server we use for PHP integration. But then I realized that Node.js is available only in Debian unstable and it has more dependencies (from unstable) then the Jenkins and Java altogether. I didn't want to break anything on this server, so I used Jenkins' Slave feature and connected to server used for JS development (so all the JS stuff is already running there).

Setting up Mocha

Mocha is a JavaScript test framework. It worked fine on the server: 

So I just needed to find out, if it has some output usable for CI. Surprisingly, it has and it works fine despite the fact, it is poorly documented :-) 

Setting up JSHint

JSHint can be installed via npm:

npm install jshint -g

It checks JS like this:

jshint myfile.js

And yes, it can produce XML report:

jshint ./app --jslint-reporter > jshint.xml

Making it all work

You need Copy To Slave, xUnit and Violations plugins in Jenkins.

We will need two Jenkins jobs. First will run all the stuff, gather the XMLs with results and trigger the reporting job. The second job will just process results and display them. This is necessary, because I realized that Violations plugin runs earlier that the Copy to Slave, and therefore, it had no data.

In the first job, we bind it to our Node.js slave and add a build step (Execute shell):

cd /var/jenkins/workspace/nodejs && mocha -R xunit > xunit.xml && jshint ./app ./public/javascripts/app/ --config .jshintrc --jslint-reporter > jshint.xml || exit 0

Then we need to gather the results from slave node via Copy to Slave plugin: 

Second job

Second job has no build steps, it only processes the results. The test results worked for me, when I set them as PHPUnit ones:

The JSHint results can be processed via Violations plugin: 

However, there is an issue when using Violations plugin for JS files. It is not possible to browse the errors in files, as it is possible for other reports. But I'm not only one who experiences this issue.

Conclusion:

We have basic continuous integration for JS code up and running. 

JavaScript community is growing strong, so I hope that there will soon be loads of different CI tools for JS. I'm only afraid of their fragmentation (There are many new JS frameworks built every day).

Citace ČSN ISO 690 ve Wordu

Pokud teď píšete bakalářku nebo diplomku, tak jste si možná všimli, že Word umí docela pěkně pracovat s citacemi (jak na ně najdete třeba tady). Problém může nastat s formátem citací.

Jaký formát citací?

Na KIT FIS máme zpracované instrukce na psaní BP/DP, kde je jako ukázka citace v dokumentu uvedeno „[Novotný, 2011, str. 56]“ (všimněte si hranatých závorek). Jenže o kousek níž je odkaz na interpretace normy na citace.com, kde jsou citace v textu doporučovány jako „Holá (2006)“ nebo „(McQuail, 2002, s. 29)“ (tedy v kulatých závorkách, a pokud je to součástí textu, tak je v závorkách jen rok). V formátu přehledu biografie jsem zatím odlišnosti nenašel.

Co s tím?

Zřejmě se budu držet hranatého formátu, který je v požadavcích, ale přehled zdrojů udělám podle ČSN ISO 690.

Problémem je, že Word tento formát neumí. Jednou z možností je použít rozšíření ČSN ISO 690 pro MS Word, ale to není úplně optimální, pokud už ve Wordu máte nějaká zdroje zadané. Tohle rozšíření totiž upravuje, která pole jsou pro který typ zdroje povinná, takže se vám to může pobláznit.

Mnohem lepší je, si balíček rozbalit třeba 7zipem a potřebný soubor CSN_ISO_690Harvard.XSL si od adresáře c:\Program Files (x86)\Microsoft Office\Office14\Bibliography\Style\ nahrát ručně.

Protože se rozšíření drží normy a ne pravidel na KITu, tak používá kulaté závorky. Zároveň jsem narazil na problém s výpisem elektronických zdrojů (zřejmě souvisí s tím, že jsem si jen změnil výpis a ne i formát zadávání citací). Pro svoje potřeby jsem si tedy XSL upravil a pokud chcete, tak ho mám na Githubu. (Používejte na vlastní nebezpečí.)

Co používám? XAMPP

Už dlouho používám pro vývoj webů na notebooku XAMPP. Jde o balík, který obsahuje nakonfigurovaný Apache, PHP a MySQL (+ některé další aplikace, které nevyužívám). Je možné ho buď využívat v portable režimu nebo standardně nainstalovat.

V čem je lepší?

Oproti běžné instalaci jednotlivých součástí samostatně je výhodou XAMPPu to, že je připravený k použití ihned – stačí rozbalit 7zip archív. Můžete také využívat dvě různé verze XAMPPu (třeba s různými verzemi PHP) a spouštět je podle potřeby.

Jsou tam aktuální verze?

Vývojáři XAMPPu se snaží udržovat všechny součásti co nejaktuálnější (v následující verzi už bude PHP 5.4).

Určitě to má nějaké problémy!

Jedinou komplikaci jsem měl s předpřipraveným PEARem, který jsem nakonec raději smazal a nainstaloval načisto.

Závěrem

XAMPP je výborný na vývoj webů, ale samozřejmě na serveru bude pro produkční nasazení vhodnější instalace jednotlivých aplikací. Může se vám hodit nastavit si ukládání odeslaných e-mailů do souboru.

Co používáte pro vývoj webů vy? Počítám, že se to bude dost lišit podle operačního systému…

V čem psát bakalářskou práci?

Mám teď rozepsanou bakalářku ve Wordu a přemýšlím, v čem udělat finální verzi. (Zbývá mi ještě čas do odevzdání, tak nad tím můžu koumat.) Na Wordu se mi totiž nelíbí několik věcí:

  • nemá dokonalou typografii
  • dokumenty se špatně verzují v GITu – není vidět jednotlivé změny, soubor je uložený binárně
  • občas se chová nečekaně, takže se bojím, že bych v závěrečné fázi někde něco upravil a celý dokument by se mohl divně přeskládat

Uvažoval jsem o DocBooku (naučil jsem se v 4IZ238) nebo TeXu (učím se teď v 4IZ552).

Docbook:

  • + sémantický formát
  • + s Oxygenem jde pěkně editovat i WYSIWYG
  • + „textový“ – půjde dobře verzovat
  • + lze z něj generovat i třeba HTML nebo ePUB
  • – nemá dokonalou typografii

TeX

  • + dokonalá typografie!
  • + „textový“ – půjde dobře verzovat
  • – píše se v něm hůře než v DocBooku

Řešení?

Tak co to napsat v DocBooku a vysázet v TeXu? Ano, to je asi cesta, kterou se vydám. Z 4IZ238 umím XSLT, takže nebude problém si napsat transformaci, která z DocBooku udělá .tex soubor. Vím, že už existují konvertory z Docbooku do TeXu, ale pokud si ji napíšu sám, tak:

  • budu vědět jak funguje (a případně si budu moct něco snadno doladit)
  • prosvištím si XSLT (asi už jsem toho dost zapomněl)
  • a budu moct (část) BP mít jako semestrálku do 4IZ552

Funkční prototyp (umí kapitoly, odstavce a obrázky s popisky), který z DocBookového XMLka udělá skrz TeX PDFko, jsme s Tomášem dali dohromady za hodinku…

Nevýhodou DocBooku a TeXu je chybějící kontrola pravopisu. Ale z DocBooku jde vygenerovat i HTML a to otevřít ve Wordu, takže to nějaký zásadní problém není.

A co vy, v čem píšete (v čem jste napsali) BP/DP?

Co používám? Xenu’s Link Sleuth

Občas používám docela užitečný program na kontrolu odkazů na webech, Xenu's Link Sleuth. Funguje tak, že mu zadáte výchozí adresu (typicky třeba hlavní stránku), on si ji stáhne, najde na ní všechny odkazy (a to jak na další stránky, tak i na obrázky, skripty a CSSka) a ty ověří. Z dalších stránek, na které první stránka odkazuje, si zase najde všechny odkazy a ty ověří…

A k čemu to?

Xenu nám pomůže odhalit chyby, které by při procházení našeho webu měli jak uživatelé, tak i vyhledávače. Můžeme nalézt dva druhy možných chyb.

  • uživatelské (obsahové)
  • programátorské

Uživatelské (obsahové) chyby

Může se stát, že se uživatel překlepne a vloží do stránky odkaz, který vede na neexistující stránku. Případně může přestat existovat stránka, na kterou odkázal v minulosti.

Programátorské chyby

Programátor může třeba špatně naprogramovat vypisování odkazů v menu nebo něco takového. Horší jsou chyby, které vytvářejí nekonečné množství stránek. Typickým příkladem je kalendář akcí, který lze po měsících procházet do hluboké minulosti nebo daleké budoucnosti. Jednou jsem spouštěl Xenu na web a divil jsem se, že kontrola trvá tak dlouho. Nakonec jsem zjistil, že už kontroluje jen kalendář akcí a je u roku 1700 a zároveň u roku 2300 na druhé straně. Googlu by se to nemuselo líbit a mohl by nás podezřívat z nějakého spamování indexu.

Takže jak na to?

Spustíme Xenu a zadáme URL webu, který chceme kontrolovat. Pod tlačítkem „More options“ se skrývají další nastavení, ale ta teď nejsou důležitá, můžete si je prohlédnout později.

Spustíme kontrolu a po doběhnutí se nám červeně zobrazí chybné odkazy. Samozřejmě ne vše jsou opravdu chyby, na následujícím obrázku jsem vybral ty, které nás zajímají:

  • [obsahová chyba] e-shop nejlevnejsitablet.cz skončil
  • [obsahová chyba] nová adresa FB stránky už je jen h*tps://www.facebook.com/shopio
  • [obsahová chyba] Dobrý Web změnil odkazy na školení – toto možná není chyba, protože DW si u sebe staré odkazy přesměrovává – ale stejně je lepší odkazovat na aktuální URL
  • [programátorská chyba] h*tp://twitter.com/Shopio/status/1.64261064014E+17/ vzniklo asi tak, že se s číslem statusu na Twitteru pracovalo jako s celým číslem a ne jako s řetězcem. Když číslo statusu přeteklo rozsah typu integer, tak se začalo brát jako desetinné číslo a to není do odkazu úplně optimální…
  • [OK] h*tp://t.co/tmyN7sM8 naopak problém není – je to Twitterový zkracovač odkazů, takže je správně, že přesměrovává

Závěrem

Kontrolujete odkazy na svém webu? Zkuste si na něj schválně pustit Xenu a podělte se o výsledky v komentářích!

Co používám? FileHippo Update Checker

Mám v PC docela dost programů, které čas od času potřebují aktualizovat. Některé se o to starají samy, nejlépe z nich asi Google Chrome, který o tom nedává ani vědět (super!). Některé se o to nestarají nebo jsem to u nich možná vypnul, protože s tím moc otravovaly :) Stejně tak některé programy, které používám v portable režimu, se samy od sebe neaktualizují a je to nutné udělat ručně.

Proč vůbec aktualizovat?

Nové verze většinou obsahují bezpečnostní opravy, nové funkce a nebo opravy chyb.

Co s tím?

Jako dobrý nástroj se mi osvědčil FileHippo.com Update Checker (FileHippo.com je obdoba českého stahuj.cz nebo slunecnice.cz).

Funguje tak, že po spuštění projde standardní adresáře, kam se instalují programy (Program Files), v nich vyhledá nainstalované programy a porovnává jejich verze s nejnovějšími verzemi ve své databázi. Po skončení kontroly se otevře webová stránka s přehledem zastaralých programů a možností stažení aktuální verze.

Nestandardní adresáře

Pokud máte aplikace nainstalované i v neobvyklých adresářích (třeba jako já ty portable), tak je potřeba to Update Checkeru říct. To uděláte tak, že po jeho spuštění vyberete volbu Settings, tam se přepnete na záložku Custom Locations, kde je můžete přidat. Poté potvrdíte pomocí OK a spustíte kontrolu znovu pomocí Retry.

Závěrem

Alternativou k Update Checkeru může být program Secunia Personal Software Inspector, který se specializuje na kontrolu, zda nepoužíváte verze programů, které obsahují již opravené bezpečnostní chyby.

A co vy, kontrolujete si aktuálnost používaných programů? Nebo to necháváte na nich a když se chtějí aktualizovat, tak je necháte?

Vodafone a 75% sleva na tarif díky ČD

Mobil používám docela málo, většinu věcí řeším online (ne přes mobil – datový tarif nepoužívám), takže se můj měsíční účet pohybuje mezi 100–200 Kč. Měl jsem u Vodafone předplacenou kartu a někdy v létě 2010 jsem chtěl přejít k T-Mobile na tarif Bav Se (platil bych ± stejně a měl bych v tom volné minuty a SMSky).

Retence u VF

U operátorů je běžné, že když chcete odejít pryč, tak vám nabídnou nějakou zajímavou slevu, abyste zůstali. Většinou se to týká hlavně tarifů, ale kupodivu mi nabídli 50% na Nabito 350, i když jsem měl předplacenku, takže jsem se nechal ukecat. Z toho je vidět, že ceny mají hodně nadstřelené, když se jim vyplatím i za polovinu.

Ale lidé postupně zjistili, že pokud nechtějí volat za draho, tak stačí naoko odcházet a vyhádat si nějakou slevu. (Diskuze o tom na Mobilmanii má přes 40 stránek). Ale samozřejmě na to operátoři postupně reagují a retenční nabídky dávají méně častěji a méně výhodné.

Nedávno se objevily různé „aférky“, že se v cizině volá mnohem levněji apod. Takže, co s tím, pokud také chceme volat levně?

Řešení levného volání

Boj za levné volání pro všechny (o což se někteří snaží), je podle mě nesmysl. V tomhle je lepší být sobec, myslet na sebe a sehnat si sám něco výhodného. Jednou z možností je zmíněná retence, ale ne každému se s nimi chce dohadovat.

Vodafone naštěstí nabízí něco lepšího. Ve spolupráci s ČD dali dohromady slevu 75% v rámci programu ČDBonus. Je na to potřeba InKarta, kterou jde objednat přes cd.cz, zaplatit kartou (150 Kč) a pak si ji za cca 2 týdny vyzvednout na vybraném nádraží. K dispozici jsou potom tarify Nabito 119 a Nabito 350 s 75% slevou (a 25% sleva na nějaká data).

Závěrem

Tyhle zvýhodněné tarify nejsou nová věc, nabízejí je už od června 2011, tak jim to třeba ještě chvíli vydrží a stihnete si je případně pořídit taky. Samozřejmě tuhle nabídku Vodafone nikde neinzeruje, protože by mu na ni přecházeli lidé, kteří jinak spokojené platí více. Podle mě to je asi nejlepší, co jde získat bez nějakého jakožeodcházení a handrkování se o slevu.

Já si to bez problémů aktivoval minulý týden, nabídka platí až do konce platnosti InKarty, což jsou tři roky, kdy nebudu muset řešit ceny volání a můžu sledovat boj ostatních s operátory.

Více informací o tarifu, případné odpovědi na časté otázky najdete v článku na Mobilmanii.