Zapewne znasz ten ból – dołączasz do nowego projektu, a przez pierwsze dni lub nawet tygodnie, przeklikujesz się przez widoki, sprawdzasz dostępne komponenty, interfejsy, poznajesz architekturę. W takiej sytuacji bardzo pomocna może być dokumentacja, dzięki której szybko przybijemy sobie piątkę z projektem i powiemy głośno – znam Cię!
Dzisiaj krótki wpis o narzędziu Compodoc – generatorze dokumentacji, która wygląda naprawdę pięknie. A co najlepsze, nie musimy nic dopisywać do kodu. Wbijamy na świeżaka do nowego projektu i ją po prostu generujemy 🙂
Compodoc
Rozpoczynamy od globalnej instalacji Compdoca:
|
1 |
npm install -g @compodoc/compodoc |
Dodajemy skrypt do package.json w projekcie:
|
1 2 3 |
"scripts": { "compodoc": "npx compodoc -p src/tsconfig.app.json" } |
Generacja dokumentacji:
|
1 |
npm run compodoc |
Tadam! Dokumentacja gotowa. Przechodzimy do katalogu documentation, który utworzył się w root directory (główny folder aplikacji) i odpalamy index.html.
Dla prostej aplikacji, wygląda to następująco:
Jak widać, możemy szybko zapoznać się między innymi z:
- podziałem modułów
- interfejsami w aplikacjami
- całym drzewem routingu
- listą komponentów, dyrektyw, serwisów
Niektóre zalety:
- kompatybilność z jsdoc
- możliwość stylowania dokumentacji
- możliwość dodawania dodatkowej dokumentacji na podstawie plików JSON z odpowiednią strukturą
- wyszukiwarka!
Cała dokumentacja:
https://compodoc.app/guides/getting-started.html
Genialne! Naprawdę cieszę się, że natrafiłem na ten artykuł. Ilość czasu jaką poświęciłem na wygenerowanie dokumentacji aktualnie prowadzonego projektu to dosłownie kilka minut..
Co prawda miałem kilka problemów ze ścieżkami importów w projekcie, a stacktrace biblioteki compodoc nie do końca wskazywał plik, w którym występuje problem, ale narzędzie naprawdę warte uwagi.