13 lipca 2011

NDoc3 - Jak wygenerować dokumentację w 5 minut?

Mam 5 minut na wygenerowanie dokumentacji


Tworzenie dokumentacji kodu źródłowego (np. publicznych typów, metod API) jest czasochłonne i "nudne". Aczkolwiek wyniki tej pracy mogą być bardzo przydatne dla programistów używających dane oprogramowanie. Ponieważ, wielu programistów lubi korzystać z dokumentacji API w formacie CHM postanowiłem dodać taki artefakt do mojego projektu Weather.com C# .NET client.  Chciałem poświęcić tej czynności minimalną ilość czasu, zacząłem więc od popularnego Sandcastle. Niestety po 20 minutach i próbach instalacji, konfiguracji, zrozumienia koncepcji poddałem się. Nie oznacza to, że Sandcastle nie jest dobrym produktem, ale moim głównym kryterium było wygenerowanie CHM'a w 5 minut.

Aby wygenerować jakąkolwiek dokumentację CHM należy zainstalować HTML Help Workshop and Documentation.  

NDoc3 na ratunek

Następnym programem który uruchomiłem był NDoc3, reaktywacja kiedyś popularnego NDoc'a. Zostałem bardzo miło zaskoczony, gdyż po 5 minutach miałem wygenerowanego CHM'a dla mojej biblioteki, który wyglądał następująco.




NDoc3 generuje plik dokumentacji w formacie CHM używając jako źródła danych pliku(ów) assembly danej biblioteki oraz pliku XML wygenerowanym przez Visual Studio na podstawie komentarzy metod/klas w kodzie źródłowym. Poniżej przykład komentarza w kodzie źródłowy, który zostal użyty do wygenerowania powyższej strony w dokumentacji.


Aby wygenerować plik XML z komentarzami we właściwościach projektu (Properties) w Visual Studio wybierz zakładkę Build i zaznacz opcję 'XML documentation file'.


Konfiguracja projektu NDoc'a (plik z rozszerzeniem .ndoc) jest bardzo prosta i składa się z kilku kroków:

  1. Konfiguracja assembly i pliku XML z komentarzami (należy kliknąć przycisk Add i pojawi się dialog - obrazek poniżej):
    1. Należy dodać assembly bibiloteki, którą chcemy udokumentować (w przykładzie to Weather.com.Client.dll)
    2. Oraz ścieżkę do pliku XML wygenerowanego przez Visual Studio.
  2. Mozna też ustawić kilka podstawowych opcji:
    1. OutputDirectory - ustawia katalog w którym zostanie wygenerowany plik dokumentacji
    2. HtmlHelpName - nazwa pliku CHM
    3. Title  - tytuł dokumentacji


Końcowy efekt powinien wyglądać następująco:


Po uruchomieniu kompilacji dokumentacji znajdziemy w folderze Doc plik Documentation.chm.

Hope this helps.

Brak komentarzy:

Prześlij komentarz

Uwaga: tylko uczestnik tego bloga może przesyłać komentarze.