Jirka Helmich

Dřív, než začnu popisovat, jak se Sandcastle pracovat, resp. řešit problémy, které s ním můžete mít, asi by se vám hodilo vědět, co to vůbec je. Jedná se o nástroj distribuovaný společností Microsoft, který vám usnadní vytvoření programátorské dokumentace. Po tom, co vyhasl život projektu nDoc, Microsoft se prý rozhodl podopořit právě Sandcastle, aby zpřístupnil programátorům pro platformu .NET podobně užitečný nástroj. Sandcastle na základě XML dokumentace (komentáře ///<sumarry>) vygeneruje HTML nápovědu kompilovanou do spustitelného souboru, případně složku plnou HTML souborů nebo dokonce ASP.NET dynamický web. A to vše jako by z oka vypadlo MSDN.

Sandcastle můžete stahovat na adrese http://www.microsoft.com/downloads/details.aspx?familyid=00535334-C8A6-452F-9AA0-D597D16580CC&displaylang=en#filelist. Vzhledem k tomu, že se jedná o konzolovou aplikaci, slabší povahy uvítají grafické rozhraní, které distribuuje server codeplex.com. Jedná se o Sancastle Help File Builder GUI, který můžete stáhnout na adrese http://www.codeplex.com/SHFB.

Když budete chtít poprvé Sandcastle vyzkoušet, narazíte na řadu chyb, ty jsou však způsobeny chybnou konfigurací projektu a SHFB. Nejprve se pokusíte o import Sandcastle projektu z projektu Visual Studia. Dozvíte se, že v projektu není nic k importu. No, ono ani být nemůže, dokud Visual Studio nevyexportuje komentáře do speciálního XML souboru do vámi specifikované lokace. Informace o dokumentačním souboru je uložena v příslušné solution, kde ji také Sandcastle hledá. V nastavení projektu je tedy třeba pod záložkou Build nastavit položku XML documentation file:

Fajn, první potíž překonána, teď už to půjde jako po másle - uklouzneme takřka okamžitě. V nabídce Documentation zvolíme Build Solution a hnedle se kocháme chybovým hlášením “BUILD FAILED: Could not find path to HTML 1.x help compiler”. V nastavení SHFB chybí cesta k HTML Help Workshop, pokud jej vůbec v systému máte nainstalován.

Já jsem si vyzkoušel vygenerování složky s HTML soubory, výsledek vypadá následovně:

Samtné SHFB pak nevypadá příliš promakaně, nicméně svému účelu výborně slouží: