Beste Wiki-Syntax für die Dokumentation in Ruby-Code und Projekt Readme-Dateien

Question

Gibt es Wiki-Syntax wie rdoc, Abschlag, ... in der Ruby-Welt zu empfehlen? Ich schreibe manchmal Open-Source-Code und habe keinen Kleber, die Syntax ich in dem Code Dokumente und in der Readme-Dateien verwenden soll. Was für mich hilfreich sein, was und warum Sie es verwenden.

Answer 1

RDoc ist der Standard-Dokumentations. Die RDoc Syntax ist die Standardeinstellung eines innerhalb Ruby-Dateien und Bibliotheken erlaubt.

Sie können feststellen, TextTile oder Markdown außerhalb Ruby-Klassen für Textdateien verwendet, wie zum Beispiel der Readme oder die Changelog-Dateien. Aber das ist nicht der Standard sintax, so dass Sie einen Weg brauchen würden den Parser zu erzählen, die Syntax, um die Datei mit geschrieben wird, in der Regel diese Art und Weise ist die Dateierweiterung.

GitHub zum Beispiel folgt genau diese Konvektion. Es sei denn, eine .textile oder .markdown Erweiterung angegeben wird, wird die Datei als RDoc analysiert.

• http://github.com/weppos/whois (.rdoc == rdoc)
• http://github.com/rails/rails/tree/master/ railties / (keine Erweiterung == rdoc, aber nicht für GitHub)
• http://github.com/technoweenie/restful-authentication /blob/master/README.textile (.textile == Textile)

Denken Sie daran: AFAIK, Inline-Dokumentation wird immer als RDoc analysiert

.

Answer 2

Auf Github verwenden die Menschen meist rdoc oder Textile als Format für die Readme-Dateien. Rdoc ist auch sehr nützlich für die API-Dokumentation von Code, wie die Syntax richtig schön in den Code integriert und ist angenehm zu lesen.