Wie schreiben Sie Ihre Paketdokumentation?

Question

Ich habe noch keinen vernünftigen Workflow zum Erstellen von Paketen und Schreiben ihrer Dokumentation gefunden.

Ich möchte so viel von dem Prozess (und der Dokumentation) wie möglich automatisch generiert werden.

Der offensichtliche Weg, dies zu tun scheint package.skeleton zu verwenden zu sein, um die Basis-Paket-Dateien zu erstellen, dann die programmüberschreiben DESCRIPTION-Datei und die Rd Dateien. Das Problem dabei ist, dass Sie dann die automatisch generierten Felder verlieren, die sicherstellen, dass Sie sich daran erinnern, alle richtigen Parameter zu dokumentieren.

Ich würde gerne wissen, wie Sie gehen über das Erstellen von Paketen und Schreiben von Dokumentation. Gibt es Tools, die den Prozess vereinfachen? (roxygen sieht aus wie es für diese Art von Sache entwickelt wurde, gibt es ein gutes Tutorial dafür und gibt es Alternativen?)

Answer 1

Ich verwende roxygen für alle meine Projekte. Durchsuchen Sie als Beispiel die Quelle nach the webvis package. Hadley verwendet auch Roxygen für seine Dokumentation (siehe z. B. seine lubridate package).

Soweit ich weiß, ist Roxygen nicht viel mehr dokumentiert als die vigette (siehe the roxygen homepage).

Roxygen ist gut, weil es zu einer lehrreichen Programmierung führt, in dem Sinne, dass Ihre Dokumentation und Ihr Code nebeneinander liegen. Dies erleichtert auch den Dokumentationsprozess, da Sie mit allem gleichzeitig arbeiten. Ich empfehle es definitiv und werde keine Pakete ohne es zu diesem Zeitpunkt entwickeln.

Das heißt, es automatisiert nicht die Dokumentation in dem Sinne, dass einige Dokumentationsgenerierungswerkzeuge (z. B. javadoc) tun: roxygen interpretiert R-Kommentare, die ordnungsgemäß formatiert sind, aber es interpretiert R-Code in keiner Weise.

In Bezug auf die Erstellung des Pakets allgemein: package-skeleton ist ideal für den Anfang. Sobald Sie ein paar Pakete erstellt haben, können Sie es in Zukunft einfacher finden, alle Verzeichnisse, NAMESPACE usw. von Hand zu erstellen. Vor allem, wenn Sie einige der anderen Praktiken befolgen, wie zum Beispiel ein Demo-Verzeichnis, die Verwendung von Roxygen, das Schreiben einer Vignette oder das Einbinden von Quellcode in andere Sprachen.

Zuletzt verwalte ich meine Pakete in Eclipse (StatET); Viele der IDEs haben "Projekt" Ansichten, die helfen, die Paketstruktur zu verwalten, so dass Sie vielleicht auch einen fortgeschritteneren Editor verwenden möchten.

Answer 2

In Bezug auf roxygen Ressourcen, einige mehr, da entstanden, ein paar mehr entstanden, my own notes zu zitieren:

Oft, wenn ich Roxygen oder Roxygen2 google habe ich Probleme bei der Suche Dokumentation.Hier ist eine Zusammenstellung einiger wichtiger Ressourcen:

• Hadley Wickham hat eine große introduction to core features of Roxygen 2

• Es gibt several vignettes listed on the Cran site for Roxygen 2

• RStudio hat Hinweise auf running Roxygen

• roxygen2 package source code on github