Jak piszesz swoją dokumentację pakietu?

Question

Nie do końca zrozumiałem sensowny przepływ pracy dla budowania pakietów i pisania ich dokumentacji.

Chcę, aby jak najwięcej procesu (i dokumentacji) było generowane automatycznie.

Oczywistym sposobem na zrobienie tego wydaje się użycie package.skeleton w celu utworzenia podstawowych plików pakietów, a następnie programowego zastąpienia pliku DESCRIPTION i plików Rd. Problem polega na tym, że tracisz automatycznie wygenerowane pola, które zapewniają zapamiętanie i udokumentowanie wszystkich właściwych parametrów.

Chciałbym wiedzieć, w jaki sposób jesteś przejść do tworzenia pakietów i pisania dokumentacji. Czy są dostępne jakieś narzędzia ułatwiające proces? (roxygen wygląda na to, że został zaprojektowany do tego typu rzeczy, czy jest tam dobry tutorial do niego? I czy są jakieś alternatywy?)

Answer 1

Używam tlenu dla wszystkich moich projektów. Na przykład wyszukaj źródło dla the webvis package. Hadley również używa roxygen do swojej dokumentacji (np. Zobacz jego lubridate package).

Zgodnie z moją wiedzą, roksygen nie jest dokumentowany zbyt daleko poza vigette (spójrz na the roxygen homepage).

Rtęć jest dobra, ponieważ prowadzi do programowania literackiego, w tym sensie, że dokumentacja i kod są umieszczone obok siebie. Ułatwia to także proces dokumentacji, ponieważ pracujesz ze wszystkim naraz. Zdecydowanie polecam i na tym etapie nie opracuję żadnych pakietów bez tego.

To powiedziawszy, nie automatyzuje dokumentacji w tym sensie, co niektóre narzędzia do generowania dokumentacji (na przykład javadoc): roxygen interpretuje komentarze R, które są poprawnie sformatowane, ale nie interpretuje w żaden sposób kodu R.

Odnośnie tworzenia pakietu ogólnie: package-skeleton jest świetny na początek. Po utworzeniu kilku pakietów może się okazać, że łatwiej będzie w przyszłości tworzyć wszystkie katalogi, NAMESPACE itp. Ręcznie. Zwłaszcza jeśli zamierzasz zastosować się do niektórych innych praktyk, takich jak dołączenie katalogu demo, używanie roxygena, pisanie winiety lub włączanie kodu źródłowego w innych językach.

Wreszcie zarządzam pakietami w środowisku Eclipse (StatET); wiele IDE ma widoki "projektu", które pomagają zarządzać strukturą pakietów, więc możesz również chcieć użyć bardziej zaawansowanego edytora.

Answer 2

dotyczące zasobów roxygen kilka więcej od tego czasu pojawiły się, jeszcze kilka pojawiły, cytując my own notes:

Często kiedy google Roxygen lub Roxygen2 mam problem ze znalezieniem dokumentacji.Oto zestawienie niektórych kluczowych zasobów:

• Hadley Wickham ma wielką introduction to core features of Roxygen 2

• Istnieje several vignettes listed on the Cran site for Roxygen 2

• RStudio ma notatki na running Roxygen

• roxygen2 package source code on github