.NET i takie tam

Sandcastle i generowanie plików pomocy

with 3 comments

Moje pierwsze zetkniecie z Sandcastle nie było najszczęśliwsze – help file – potrzebny był ‚na wczoraj’ a tu, dostępną miałem linie poleceń i masę parametrów, których ilość nie nastrajała optymistycznie. Mówiąc krótko byłem zawiedzony.

Minęło trochę czasu i znów zmuszony byłem stworzyć plik pomocy – postanowiłem ponownie spróbować Sandcastl’a. Cóż, jeśli chodzi o sam pakiet to niewiele sie w nim zmieniło – inny numerek, ale cały czas mało przyjazny dla użytkownika. To że ktoś zajmuje sie programowaniem nie musi oznaczać, ze kocha grzebanie w linii komend. Co jednak od razu zauważyłem, w Gogolu pojawiło sie sporo dodatkowych narzędzi których celem było ułatwienie pracy z naszym zamkiem z piasku. Od prostych skryptów *.bat – po ‘full blown’ aplikacje jak np. Sandcastle Help File Builder.
Ten ostatni uznałem za wyjątkowo pomocny – gdyż odgradza nas od samego pakietu Sandcastle i możemy zapomnieć że coś takiego w ogóle instalowaliśmy. Teraz generowanie pomocy jest proste:

1. Przede wszystkim potrzebujemy XML z zawartością naszej pomocy. Plik ten może zostać wygenerowana prze Visual Studio wystarczy wejść na zakładkę Build we właściwościach projektu i w sekcji Output będziemy mieli pole XML documentation file. Po zaznaczeniu VS określi sobie domyślna ścieżkę – która oczywiście możemy zmienić.

XML document file

2. Kiedy mamy już plik pomocy – przechodzimy do naszego help builder’a – Tworzymy nowy projekt – następnie za pomocą przycisku Add wskazujemy gdzie jest wyżej wymieniony plik XML i assembly do którego sie odnosi. Następnie jeśli nasz projekt posiada referencje do innych dll’ek – musimy wskazać ich położenie w Project Properties -> Build -> Dependences i gotowe. Wystarczy wcisnąć przycisk buduj – i po chwili mamy gotowy plik pomocy.

Sandcastle Help File Builder

Oczywiście możemy zdefiniować format pliku pomocy – od *.hlp przez *.chm po najnowsze pliki pomocy integrujące sie z pomocą VS, możemy dodać dodatkowa zawartość pomocy, jak własne opisy itp. w postaci html’a – i wiele innych opcji.
Tak na marginesie tworzenie komentarzy na pewno usprawni wam plug-in GhostDoc do Visual Studio.

Written by sakowicz

Maj 2, 2007 @ 8:05 am

Napisane w .NET, Tools

Odpowiedzi: 3

Subscribe to comments with RSS.

  1. Witam.

    Fajny artykuł i pomocny bardzo.🙂 Ale chciałbym się dowiedzieć od jego autora, jak wygenerować drugi typ dokumentacji, bo zwraca mi komunikat że nie może znaleźć kompilatora do tego typu, oraz czy jest więcej typów lub template-ów dokumentacji? Jeśli tak to skąd można je ściągnąć itd…

    Pozdrawiam.

    truthseeker

    Październik 5, 2008 at 6:38 pm

  2. Jak na razie nie potrzebowałem zmieniać niczego w moim procesie generowania dokumentacji, jak tylko zajdzie taka potrzeba zagłębię się ponownie w temat izaktualizuję post.

    sakowicz

    Październik 6, 2008 at 10:07 am

  3. Aby generować dokumentacje w postaci plików HXS konieczne jest zainstalowanie Visual Studio 2008 SDK Version 1.0
    link:
    http://www.microsoft.com/downloads/details.aspx?FamilyID=30402623-93ca-479a-867c-04dc45164f5b&displaylang=en

    Czort

    Czerwiec 10, 2009 at 8:09 am


Skomentuj

Wprowadź swoje dane lub kliknij jedną z tych ikon, aby się zalogować:

Logo WordPress.com

Komentujesz korzystając z konta WordPress.com. Log Out / Zmień )

Zdjęcie z Twittera

Komentujesz korzystając z konta Twitter. Log Out / Zmień )

Facebook photo

Komentujesz korzystając z konta Facebook. Log Out / Zmień )

Google+ photo

Komentujesz korzystając z konta Google+. Log Out / Zmień )

Connecting to %s

%d bloggers like this: