Ani som nechcel tento článok napísať, lebože iba keď si tým obhyzdným peklom jeden prejde, pochopí že stav alarmujúci jest.

YUIDoc je semä hada britského, čiže potrebujete Python. Okrem toho jačí po 4 daľších knižniciach. Bez command prompt cez nasledovné neprejdete.

Python 2.6

  1. Stiahnite si Python 2.6.5 Windows installer
  2. Nainštalujte. Doporučujem nemeniť cieľovú cestu a horko prijať čo má inštalátor prednastavené, inak sa môžete dostať do slušných sračiek.
  3. Do PATH si pridajte C:\Python26 a C:\Python26\Scripts.

setuptools

setuptools je balíček, ktorý zjednodušuje sťahovanie a inštaláciu ostatných balíčkov pre Python.

  1. Stiahnite si setuptools-0.6c11.win32-py2.6.exe. Bacha aby ste fakt stiahli verziu py2.6, inak budú problémy.
  2. Nainštalujte.

Ostatné závislosti pre YUIDoc

  1. Spustite command prompt a postupne nainštalujte každý z nasledujúcich balíčkov. Pokiaľ by vám systém protestoval, že použitý easy_install nevie nájsť, skúste nasledové spúšťať z adresára C:\Python26\Scripts.
  2. easy_install Pygments
  3. easy_install SimpleJSON
  4. easy_install Cheetah

Mne v bode 4. Cheetah zlyhal na tom, že si nevedel nájsť práve stiahnutý inštalátor pre Markdown:

...
Downloading http://sourceforge.net/projects/python-markdown/files/markdown/2.0.3/Markdown-2.0.3.win32.exe/download
Processing download
error: Couldn't find a setup script in c:\docume~1\martin~1.bal\locals~1\temp\easy_install-ad29ft\download

Pre istotu som teda Markdown stiahol a nainštaloval samostatne. Sám netuším či to má význam.

YUIDoc

Stiahnite si YUI Doc. Niekam ho rozbaľte (ideálne keď cesta nebude obsahovať medzery v názvoch súborov). Ja mám napríklad adresár D:\work\libraries kde mám rôzne podobné taľafatky. Z neho mám urobený samostatný disk takto:

subst L: D:\work\libraries

Baťák sa mi spúšťa po štarte, takže L: mám vždy po ruke.

YUIDoc má v sebe ukážkový spúšťačno-konfigurujúci L:\yuidoc\bin\example.bat ktorý si je potrebné niekam skopírovať a upraviť podľa potreby. A pretože YUIDoc vo verzii 1.0.0b1 používa deprecated modul Sets som si urobil ešte malú úpravu na poslednom riadku, ktorá zakáže veselé DeprecatedWarning ňuf-ňuf správičky. Tu máte môj generate.bat:

@ECHO OFF

REM ##########################################################################

REM The location of your yuidoc install
SET yuidoc_home="l:\yuidoc"

REM The location of the files to parse.  Parses subdirectories, but will fail if
REM there are duplicate file names in these directories.  You can specify multiple
REM source trees:
REM      SET parser_in="c:\home\www\yahoo.dev\src\js c:\home\www\Event.dev\src"
SET parser_in=""

REM The location to output the parser data.  This output is a file containing a
REM json string, and copies of the parsed files.
SET parser_out="..\..\temp\doc"

REM The directory to put the html file outputted by the generator
SET generator_out="..\..\dist\doc"

REM The location of the template files.  Any subdirectories here will be copied
REM verbatim to the destination directory.
SET template="%yuidoc_home%\template"

REM The project version that will be displayed in the documentation.
SET version="1.0.0"

REM The version of YUI the project uses.
SET yuiversion="2"

python -W ignore::DeprecationWarning %yuidoc_home%\bin\yuidoc.py %parser_in% -p %parser_out% -o %generator_out% -t %template% -v %version% -Y %yuiversion%

Popis jednotlivých parametrov je v dodávke celkom jasný. Pre úplnosť uvediem ešte štruktúru môjho projektu:

  • dev\js Obsahuje moje JS súbory a aj uvedený generate.bat, ktorý z toho adresára spúšťam (bacha, uvedené cesty sú relatívne k tomuto adresáru).
  • dist\doc Sem sa mi vyleje dokumentácia v HTML.
  • temp\doc Sem tratí YUIDoc dočasné súbory.

Mľaskavo vychutnávajte.