Wie schreiben Sie Ihre Paketdokumentation? [geschlossen]
-
28-09-2019 - |
Frage
Ich habe nicht ganz aus einem vernünftigen Workflow rechne für-Pakete und deren Dokumentation zu schreiben.
Ich möchte so viel von dem Prozess (und der Dokumentation) wie möglich automatisch generiert werden.
Der offensichtliche Weg, dies zu tun scheint zu sein, package.skeleton
zu verwenden, um die Basis-Paket-Dateien zu erstellen, dann programmatisch die DESCRIPTION
-Datei und die Rd
Dateien überschrieben werden. Das Problem dabei ist, dass Sie dann die automatisch generierten Felder verlieren, die Sie in Erinnerung gewährleisten haben alle die richtigen Parameter zu dokumentieren.
Ich würde gerne wissen, wie Sie gehen über Pakete bauen und Dokumentation zu schreiben. Gibt es irgendwelche Werkzeuge zur Verfügung, um den Prozess zu erleichtern? ( roxygen sieht aus wie es war für diese Art der Sache entworfen ;? ist es für sie ein gutes Tutorial und gibt es Alternativen)
Lösung
ich für alle meine Projekte roxygen. Ein Beispiel, nach der Quelle für das webvis Paket . Hadley verwendet für seine Dokumentation auch roxygen (siehe zum Beispiel seines lubridate Paket ).
Nach bestem Wissen und Gewissen, ist roxygen nicht viel über die vigette dokumentiert (einen Blick auf die roxygen Homepage ).
Roxygen ist gut, weil es zu lesen und Programmierung führt, in dem Sinne, dass Ihre Dokumentation und Code ist Seite an Seite. Dies macht auch die Dokumentation Prozess ein wenig einfacher, da Sie mit allem, was gerade arbeiten auf einmal. Ich kann es auf jeden Fall empfehlen, und entwickeln keine Pakete ohne es an dieser Stelle.
sagte, dass es nicht in der Dokumentation im Sinne automatisieren, dass einige Dokumentation Generation Tools tun (zB javadoc): roxygen interpretiert Kommentare R, die richtig formatiert sind, aber nicht R-Code in irgendeiner Weise interpretieren <. / p>
Im Hinblick auf die Erstellung des Pakets im Allgemeinen: package-skeleton
ist für den Anfang. Sobald Sie ein paar Pakete erstellt haben, können Sie es leichter, in die Zukunft finden nur alle Verzeichnisse zu erstellen, Namensraum usw. von Hand. Vor allem, wenn Sie gehen einige der anderen Praktiken folgen, wie zB ein Demo-Verzeichnis, mit roxygen, eine Vignette zu schreiben oder mit Quellcode in anderen Sprachen.
Schließlich leite ich meine Pakete in Eclipse (StatET); viele der IDE haben „Projekt“ Ansichten, die helfen, die Paketstruktur der Verwaltung, so dass Sie auch eine erweiterte Editor verwenden möchten.
Andere Tipps
In Bezug auf roxygen Ressourcen, einige mehr, da entstanden, ein paar mehr sind entstanden, um Zitat meine eigenen Notizen :
Oft, wenn ich google Roxygen oder Roxygen2 Ich habe Probleme bei der Suche Dokumentation. Hier ist eine Zusammenstellung einiger wichtiger Ressourcen:
Hadley Wickham hat eine große Einführung in Kern Roxygen verfügt über 2
Es gibt mehrere Vignetten auf der Cran Website aufgeführt für Roxygen 2
RStudio hat Hinweise auf Roxygen laufen