Wie bearbeite ich eine Readme-Datei mit rdoc zu Anzeige Ruby-Skript Hilfe / Nutzung info

Question

Ich möchte meine Nutzung documenation in einer Readme-Datei halten (duh) statt Kommentare an der Spitze von meinem Skript. Wie erhalte ich RDoc :: Nutzung der Nutzungsinformationen aus der readme anstelle der Skript Kommentare zu ziehen?

Answer 1

RDoc ist so konzipiert, eine Quelldatei, Blick auf den Kommentare zu analysieren und deren Standorte, bauen Querverweisen der Variablen, und, wenn Sie fertig ist, sie alle in einen anständigen Ausgang binden. Da RDoc zur Arbeit gegen Quelldateien ausgelegt ist, ist es vielleicht nicht die beste Wahl sein für das, was Sie tun mögen.

Stattdessen möchten Sie vielleicht schauen Sie in Yard , die tagbasierten ist. Kann ich meine README.textile in meine RDoc mit der richtigen Formatierung erhalten? hat einige nützliche Informationen für Sie.

In jedem Fall, wenn Sie die App nicht bekommen kann eine Readme-Typ doc zu analysieren, wie Sie möchten, können Sie in der Lage sein, es zu fälschen, indem Sie alle Ihre Dokumente in der Datei setzen, zusammen mit Klasse und Methoden-Stubs so die Parser können die Parameter, Globals greifen, und andere „Dingsbums“ sie brauchen nutzbare Dokumentation zu erstellen.

Sonst 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 nicht schwer, überhaupt zu tun, und die Ausgabe kann sehr befriedigend sein. Es ist ziemlich erstaunlich, wie gut ein Job RDoc tun kann.

Answer 2

Ich bin sicher nicht erfahren genug, um Ihnen die Antwort zu sagen, aber gestatten Sie mir einen Rat.

Die meisten Entwickler sind unwahrscheinlich, dass jemals in der Dokumentation zu aktualisieren, auch wenn es 3 Zeilen Code über die Umsetzung.

Sie einen Gefallen und macht nicht den Prozess noch schwieriger.

Keeping allgemeine Dokumentation getrennt ist eine nette Idee, aber, aber es hat nichts sowieso in Ihrer RDoc-generierte Ausgabe zu tun.