Dokumentace zdrojů pro shell - shocco

1.9.2011 17:59 | Přečteno: 1680× | Jen tak na okraj | | poslední úprava: 1.9.2011 18:12

Je dobré čas od času zčeřit usazené vody a já tak díky takovému kroku a novému spolupracovníku Michalovi "objevil Ameriku". Konečně jsem našel utilitu, která umožňuje kloudně dokumentovat moje shellové skripty.

Což o to. Komentáře píšu obsáhlé, ale chyběl mi nějaký způsob, jak z nich vydolovat něco, co by se přeci jenom trochu lépe četlo. U Michala jsem zahlédl utilitu s názvem docco a tou mě přivedl k alternativě pro shellové skripty, která se jmenuje - jak jinak - shocco.

Vtip je v tom, že tahle utilita zpracovává Markdown syntaxi v zakomentovaném kódu a generuje statické, dvousloupcové html, které má vlevo plky a vpravo očištěný kód. Není tedy třeba zrakem lovit kousky kódu v hromadě komentářů

Myslím, že ukázka takového vygenerovaného html je lepší než tisíc keců..

Update: Jak to nainstalovat na debianu..

sudo apt-get install python-pygments gem2deb nodejs markdown
...
sudo gem2deb ronn
...
sudo dpkg -i ruby-ronn_0.7.3-1_all.deb
...
git clone git://github.com/rtomayko/shocco.git
...
cd shocco
./configure
...
make
...

Instalovat to není nezbytně nutné. Funguje to tak, že to generované html z předhozeného skriptu sype na stdout.

       

Komentáře

[lightbringer]

Mel bych dotaz. S temito vecmi si hrajete v pracovni dobe nebo v soukromem case? Pokud v pracovni dobe, tak je to tedy slusne poruseni pracovni kazne. Paneboze dej nam rychle soukrome vysoke skolstvi, kde se nebudou zamestnanci nedoukove flakat za dane slusnych lidi.

[w4rr10r]

Nenapadlo tě, že by mohl v pracovní době pracovat tak efektivně, že by občas nemusel pracovat, že?

[Aleš Kapica]

Klid. Nic mě tak nedokáže pobavit a vyvolat blahosklonný úsměv na tváři, jako výše uvedená reakce. Dotyčný jak se zdá absolutně neví, která bije. Ano. Věnuji se takovým věcem v pracovní době. Stejně tak, jako se ve svém osobním volnu věnuji pracovním věcem.

[lightbringer]

Kdyz vam to bude tolerovat soukromy zamestnavatel, proc ne. Ale verejne vysoke skoly jsou placeny v soucasne dobe bohuzel statem, takze je smutne, ze vam toto prochazi. A na cloveka, ktereho zivi stat, mate pane nejak vysoke sebevedomi.

[Aleš Kapica]

Vážený, měl byste si laskavě uvědomit, že na vysokých školách se už dááávno neplatí všude všechno z daní. Vaše reakce mi připadá jak z jiného světa, neboť člověka, který má o věci trochu přehled by něco podobného ani nenapadlo napsat. Ano. Mám docela vysoké sebevědomí. Možná je to tak trochu i tím, že jsem jediný zaměstnanec na katedře - vyjma našeho údržbáře, který žádný titul nemá. Pokud jde o výši platu - je to z mého pohledu tak trochu charita, kterou však vyvažují skvělí kolegové a spolupracovníci a především absolutně pohodové a tvůrčí prostředí.

Je to staré a otřepané, ale nezbývá mi než to oprášit. Kdo myslíte že je lepší administrátor (údržbář, šéf,..)? Ten který lítá jak fretka, a nebo ten co se věnuje v pracovní době věcem o nichž soudí že jimi pomůže jiným, místo toho aby se dloubal v nose? Odpověď je prostá vážený - ten druhý, protože mu všechno funguje.

Krom toho. Za seznámení a zaučení do práce s podobnými "blbinkami" jako je ta, které je věnován tenhle blogpost, se v komerční sféře platí těžké háky. Jen se seznamte kupř. s tím kolik stojí třeba takové školeníčko na skriptování v shellu, kde vás stihnout za ty tři dny seznámit leda tak se základy, které najdete na kdejakém webu - 12 klacků vážený.

[Aleš Kapica]

Ale jděte na to. Jednak zjistíte o čem vlastně byla v blogpostu řeč, a také tímto krokem podpoříte živobytí mého zdejšího fanouška, který - na rozdíl ode mne - netyje z vašich daní, ale vydělává své korunky poctivě v potu tváře.

[lightbringer]

A z ceho je tedy financovano verejne vysoke skolstvi? Rad se necham poucit. Myslim si, ze majoritne ze statniho rozpoctu. To, co se vybere od studentu, sponzoru a spolecnosti v aplikovanem vyzkumu, bude jen par procent.

To ostatni jsou irelevantni reci. Kdyz je to charita, bezte nekam jinam.

Ochota ucit se nove veci vas slechti, ale melo by to byt ve vasem volnem case - pokud vam to tedy neumoznuje pracovni smlouva, to by byla jina. Osobne bych vam to jako zamestnavatel v zadnem pripade netoleroval. Alespon je videt, jak to chodi na zatuchlych a zbytnelych statnich (a statem financovanych) institucich.

[Aleš Kapica]

Nejste politik? Máte totiž podobně omezené a úchylné uvažování. Tak jako na úřadě platí že klientem je občan, kterému služby poskytuje úředník a úředníkovi (nikoliv občanu) zajišťuje servis zaměstnanec IT, přestože je formálně veden jako úředník. Tak na škole platí, že klientem je student, kterému služby poskytuje vyučující a oběma zajišťuje servis zaměstnanec IT. A to jsou ty peníze ze kterých mě platí. Proto se také na mě nevztahují pravidla podle kterých jsou financováni vyučující a podmínky, na jejichž základě získávají své tituly. Můj plat není dán tabulkami, ale smlouvou. A pokud jde o náplň mé pracovní doby - o té rozhodují potřeby mých klientů - tj. vyučujících a nikoliv vaše zbožné přání, aby - kdo nemá titul - táhnul k lopatě.

[lightbringer]

Jste zamestnanec verejne vysoke skoly? Patrne ano, takze vase vyplata pochazi majoritne ze statniho rozpoctu. Vase slovickareni nic nevyresi, proste vas zivi stat a plati vas danovi poplatnici. Tudiz je od vas nehezke, ze se v pracovni dobe flakate. Statnim zamestnancum (nebo statem zivenym, abyste byl spokojen) by se nemelo nic tolerovat, protoze na to doplaci slusny danovy poplatnik.

[Aleš Kapica]

Podobnou "přestřelku" jsem měl v jedné z diskuzí na tomto webu před nějakým časem i s panem Šimerdou, na kterého odkazuji o kousek výš, proto se nechci opakovat. Jste-li alespoň trochu počítačově gramotný, jistě si ji zvládnete dohledat sám. Každopádně i on v závěru uznal, že finance na mou mzdu skutečně z jeho daní nejdou.

Jenže na vás se nejspíš musí více polopaticky.

Jaký je podle vás rozdíl mezi penězi ze státní kasy, které tečou na státní zakázky a těmi, které tečou do školství? Máte radši, když si za peníze, které jste odvedl na daních někdo staví soukromé hotely, za babku skupuje původně státní pozemky a na nich staví projekty, které opět dotuje stát? A nebo by vám bylo milejší, kdyby tyto odvedené peníze generovaly něco, co by zvyšovalo kvalifikaci všech, co mají zájem se něco naučit a dozvědět? Odpovězte si sám. Tou smutnou pravdou je, že dnešní vysoké školství je nuceno žít především z grantů, ze kterých se platí i náklady na lidi jako jsem já. A zrovna náš stát se na těch grantech dvakrát nepředá. Ovšem moje výhoda je, že pracuji pro lidi, kteří peníze získat umí - proto se mám na školské poměry docela dobře.

Ovšem jak se říká - "ráno je moudřejší večera". Takže mě napadlo, že tím, co ve vás vyvolalo touhu odhalit dalšího darmožrouta daňových prostředků, byl onen skutečně triviální skriptík, který posloužil jako ukázkový zdroj pro shocco_example.sh takže mi nezbývá než malý exkurz do historie.

Ten skriptík byl jeden z mých prvních, ještě když jsem nastoupil na úřadě. Mí kolegové tehdy trávili hromadu času obcházením úředníků a přenastavováním jejich uživatelských profilů. Využil jsem tedy toho, že všechny jejich linuxové profily se připojovaly přes NFS a ve skutečnosti byly soustředěny v jednom adresáři na serveru.

Nebylo tedy nic snazšího, než ty jejich profily postupně skriptem procházet a nahrazovat hodnoty prázdné za ty správné. Takže jsem napsal ten skript jako jakýsi template pro kolegu co to měl tenkrát na starosti.

Nyní pár řečnických otázek: "Stále se domníváte, že je podobné hraní porušováním pracovní kázně? Stále se domníváte, že kvalitní dokumentace a utility pro její zpracování jsou nepodstatné blbosti? Jste vůbec schopen připustit, že jste se mýlil a svým názorem tak demonstroval svou vlastní krátkozrakost?"

[pavlix]

Podobnou "přestřelku" jsem měl v jedné z diskuzí na tomto webu před nějakým časem i s panem Šimerdou, na kterého odkazuji o kousek výš, proto se nechci opakovat. Jste-li alespoň trochu počítačově gramotný, jistě si ji zvládnete dohledat sám. Každopádně i on v závěru uznal, že finance na mou mzdu skutečně z jeho daní nejdou.

Aleši, dodej odkaz. Nepamatuju si, že bych se kdy s tebou dohadoval o financování veřejného školství. Spíš mi přijde, že máš nějaký osobní problém, který se snažíš řešit psaním mého jména jako magické formule na všechno :).

[Aleš Kapica]

Omlouvám se, zmýlil jsem se. Nebyla to "přestřelka" s tebou, ale s druhým mým zdejším fandou, kterým je trekker.dk, a to v debatě pod mým blogpostem na téma Jakou cestou by se mělo ubírat české školství?. Ještě link na příslušnou pasáž.

Nic to ale nemění na faktu, že výše uvedenému pánovi doporučuji návštěvu tvého kursu, aby se a) trochu dostal do obrazu a za b) ti tak dal férovou možnost vydělat.

[podlesh]

Ochota ucit se nove veci vas slechti, ale melo by to byt ve vasem volnem case - pokud vam to tedy neumoznuje pracovni smlouva, to by byla jina. Osobne bych vam to jako zamestnavatel v zadnem pripade netoleroval.

Podle podmiňovacího způsobu soudím že zaměstnavatel nejste. Dovolil bych si dobrou radu - nezkoušejte to, zřejmě na to nemáte vlohy a nedopadlo by to dobře (pokud se, samozřejmě, nepřisajete na nějaký pěkný penězovod).

Ale nic si z toho nedělejte - trenéra reprezentačního družstva také nemůže dělat každý a přesto lze v každé pivnici vyslechnout spoustu podobně laděných názorů.

[Grunt]

Ochota ucit se nove veci vas slechti, ale melo by to byt ve vasem volnem case

A co jiného by v pracovní době měl dělat? (Myslím jiného než to samovzdělávání se a hraní si – zvlášť pokud je zaměstnancem VŠ…to by si měl hrát 2× a učit se 3×)

[Bystroushaak]

No, tak nám v prváku na tul říkal Konopa, že stát pokryje asi 50% rozpočtu (teď jsem nahlédl do sešitu a je to 450 000 000 stát, 550 000 000 škola musí sehnat sama), které navíc dluží.

[Voransky]

Vím, že to napsalo již několik lidí pode mnou, ale nedá mi nekomentovat. I kdyby byl pan Aleš placený z našich daní, byl bych rozhodně proto aby dané peníze dostal někdo, kdo dělá něco konstruktivního - hledá zjednodušení dané práce - než někdo typu naší studijní referentky, která v dané době (rozuměj vše fungujejak má, tudíž mám čas) raději jde na kafe a na "drby", což ji bohužel nespraví natolik aby se alespoň na jednoho studenta dokázala tvářit příjemě (VŠCHT/FCHT - rok zpět)... Mám rád lidi, kteří svou práci dělají natolik dobře, že jim zbývá čas na hledání "zlepšováků", zvlášť když se o ně podělí s okolním světem. A má snad to, že děláte ve státním sektoru znamenat, že neděláte/neumíte nic jiného než za co jste placeni? Upřímně, takoví lidé dokáží spíš dožrat než potěšit..

[okbob]

Ze by ukolem admina bylo jen oprasovani pocitacu, a vymena toneru?

[Grunt]

Paneboze dej nam rychle soukrome vysoke skolstvi

Jo a tam to chodí jak? Tak, že s tím na co přijdou už se ani nemusí díky zafinancování dělit, ale můžou to použít pro dobro lidstva? IMHO Aleš Kapica splnil svůj úkol na 120%, protože už se o to rozdělit, do toho ho nikdo nenutil (doufám) .

[pc2005]

+1 Jo taky mě vrtá hlavou co na tom lightbringerovi vadí. Aleš Kapica objevil prácizjednodušující program a za peníze daňových poplatníků (pokud by to byla pravda) se s tím rozdělil s daňovými poplatníky.

[okbob]

S necim podobnym jsem se setkal uz pred lety - uz nevim jak se to jmenovalo. V jednom sloupci byl zaznamenan kod a v druhem (doplnenym i schematickymi znackami) byl komentar. Nevzpomenete si nekdo na nazev? Prijde mi to, jako super zalezitost, a zvlast, pokud by se to dalo snadno vygenerovat.

[TM]

lightbringer je zřejmě nemocný člověk nakažený virem ODS-HOP09. Panu Kapicovi doporučuji, aby se podobnými individui nenechal otrávit a přeji mu hodně úspěchů.
Nikdy jsem nedělal ve státním sektoru a pokud by pan Kapica byl můj podřízený, ještě jej pochválím, že jako administrátor, když mu zrovna vše jede, přemýšlí jak zlepšit komentování a dokumentaci scriptů...

[martyone]

+1

[Jindřich Makovička]

Hezké, a když se v HTML hlavičce opraví http-eqiv na http-equiv, tak se ta dokumentace dá i číst :)

[Aleš Kapica]

Napiš report autorovi shocco, jistě to ocení..

[Bystroushaak]

Ta dokumentace (výstup) je dost pěkná, líbí se mi víc než takový epydoc (používal jsem v pythonu), nebo ddoc (D).