Ich möchte meine Verwendung Dokumentation in einer Readme-Datei (duh) statt Kommentare an der Spitze meines Skripts zu halten. Wie erhalte ich RDoc :: Verwendung, um die Nutzungsinformationen aus der Readme statt der Skriptkommentare zu ziehen?Wie bearbeite ich eine Readme-Datei mit Rdoc zur Anzeige von Ruby Skript Hilfe/Nutzungsinformationen
RDoc wurde entwickelt, um eine Quelldatei zu analysieren, die Kommentare und ihre Positionen zu betrachten, Querverweise der Variablen zu erstellen und, wenn dies erfolgt ist, alles in eine anständige Ausgabe zu verknüpfen. Da RDoc entwickelt wurde, um gegen Quelldateien zu arbeiten, ist es möglicherweise nicht die beste Wahl für das, was Sie tun möchten.
Stattdessen möchten Sie vielleicht in Yard suchen, die Tag-basiert ist. Can I get my README.textile into my RDoc with proper formatting? hat auch einige nützliche Informationen für Sie.
In beiden Fällen, wenn Sie die App nicht erhalten können, um ein README-Dokument wie gewünscht zu parsen, können Sie es spoofieren, indem Sie alle Ihre Dokumente in die Datei schreiben, zusammen mit Klassen- und Methoden-Stubs Die Parser können die Parameter, Globals und andere "Was-sind-nicht", die sie brauchen, um brauchbare Dokumentation zu erstellen, greifen.
Andernfalls werden Sie wahrscheinlich die automatisierte Hilfe zu verzichten, haben mit und geben Sie sie alle in.
Meine Empfehlung ist es, die RDoc Weise zu tun, und Dokument in Ihrem Code. Es ist überhaupt nicht schwer, und die Ausgabe kann sehr zufriedenstellend sein. Es ist erstaunlich, wie gut ein Job mit RDoc funktioniert.
Ich bin sicherlich nicht erfahren genug, um Ihnen die Antwort zu sagen, aber bitte erlauben Sie mir einen Ratschlag.
Die meisten Entwickler werden wahrscheinlich nie die Dokumentation aktualisieren, auch wenn es 3 Zeilen Code über der Implementierung ist.
Machen Sie einen Gefallen und machen Sie den Prozess nicht noch härter.
Die allgemeine Dokumentation zu trennen ist zwar eine nette Idee, aber sie hat sowieso nichts mit Ihrer RDoc-generierten Ausgabe zu tun.
Ja, nachdem ich mir die Quelle näher angeschaut habe, sehe ich, dass es nicht ganz so funktioniert, wie ich es mir vorgestellt habe. Und zweitens könnte es auch gut sein, sie in der Quelle zu belassen (ich dachte, die Readme könnte leichter zu finden sein, als das richtige Skript im bin-Unterverzeichnis des Pakets zu finden, aber wahrscheinlich nur marginal). – fakeleft
Ich denke, das sind die gleichen Argumente, die zu RDoc in erster Linie führen. Ich finde, dass es ein Problem ist, getrennte doc-Dateien zu verwalten, aber es ist keine große Sache, inline zu dokumentieren, besonders wenn RDoc diese auslesen und in brauchbare Dateien umwandeln kann. Werfen Sie einen Blick auf Yard. Ich habe einige Kommentare von einer anderen Seite gesehen, wo jemand sie über eine separate Datei für ihre Dokumente verwendet hat. –