Chciałbym dołączyć informacje o zadaniach Rake w naszej aplikacji Rails. Do dokumentacji używamy YARD, a obecnie strony takie jak lib/tasks/development.rake pojawiają się domyślnie jako niesformatowany tekst.Jak udokumentować zadania rake z YARD?
Mogę sprawić, że będą renderowane jako kod źródłowy Ruby przy użyciu # @markup rubyfrom the YARD documentation.
Jednak to powoduje, że wszystkie komentarze są wstawiane, nawet jeśli zawierają one wytyczne YARD, takie jak # @!method foo. Oznacza to, że the YARD documentation on tagging DSLs nie wydaje się mieć zastosowania.
Czy brakuje mi czegoś?
W jaki sposób mogę przekonać YARD do rozpoznawania kodu w porównaniu do dokumentacji w plikach .rake?
N.B. Byłbym zadowolony z rozwiązania, które ignoruje rzeczywisty kod i po prostu generuje kopię dokumentacji, ale źródłem kopii dokumentacji musi być sam plik .rake - Nie chcę, aby dokumentacja znajdowała się w oddzielnym pliku .markdown (lub czymkolwiek), ponieważ istnieje zbyt duża szansa na zsynchronizowanie.
Więcej info - komenda yard:
używam plik .yardopts zawierające następujące:
--asset graphs 'app/**/*.rb' 'lib/**/*.rb' - README info/*
Aby uzyskać stoczni czytać zadania Rake mogę dodać 'lib/tasks/*.rake'po na łącznik (np. dodaj pliki Rake do listy "Pliki" YARD), ale jak wspomniano powyżej, nie przetwarza się ich poprawnie.
Zgodnie z sugestią Benjamina poniżej, próbowałem dodając 'lib/tasks/*.rake'przed łącznik (czyli dodawanie plików Rake do listy zwykłych plików Ruby do przetworzenia), ale nie wydaje się, aby wygenerować w ogóle nic.
Możliwe, że YARD generuje coś, ale nie w oczekiwanej lokalizacji/z oczekiwaną nazwą pliku. Przypuszczam, że nie jestem wystarczająco zaznajomiony z działaniem YARD, aby dowiedzieć się, czy gdzieś jest osierocone wyjście. W wyszukiwaniu generowanym przez Yarda z pewnością nie ma nic odpowiedniego, a prosty find doc | grep rake lub find doc | grep basename_of_rake_file nic nie pokazuje.
Czy to jest po prostu sprawienie, aby Yard rozpoznał pliki '* .rake' jako ruby? – ipd
Obawiam się, że od tego czasu nie patrzę na tak wiele, ale przypuszczam, że tak jest, tak. Jednak właściwie _kreślenie_, że są one Ruby z dyrektywą '# @markup ruby' nie działa, ponieważ _only_ renderuje Ruby, tj. Nie przetwarza już komentarzy do dokumentacji – Leo
@Leo, czy określa rozszerzenie rake'a w pomocy wiersza poleceń? _yardoc * .rake -o out/_? – benjamin