Wie verwende ich eine Markdown-Datei als Hauptdatei für Rdoc (in einem Rails-Projekt)?

Question

Ist es möglich, eine readme.md-Datei mit einem Rails-Projekt zu verwenden und rdoc auf der Hauptseite zu verwenden? Ich habe versucht, meine Rake-Aufgabe wie folgt einzurichten, aber die index.html-Seite, die generiert wird, hat einen Platzhaltersatz. Wenn ich zu README.rdoc ändere, funktioniert es wie erwartet und enthält den Inhalt der Datei.

Ich versuche auch, TomDoc zu verwenden, was, denke ich, Dinge komplizieren könnte, nicht sicher.

RDoc::Task.new :rdoc do |rdoc| 
    rdoc.main = "README.md" 

    rdoc.rdoc_files.include("README.md", "doc/*.rdoc", "app/**/*.rb", "lib/**/*.rb", "config/**/*.rb") 

    rdoc.title = "My Documentation" 
    rdoc.options << "--all" 
    rdoc.options << "--line-numbers" 
    rdoc.markup = "tomdoc" 
    rdoc.rdoc_dir = "rdoc" 
end 

Answer 1

Es ist nicht wirklich eine Antwort auf Ihr Problem, aber wenn Sie eine gute Alternative wollen:

Verwendung YARD

und verwenden Sie diese Tipps:

https://github.com/lsegal/yard/issues/404

Ich nehme an Wenn Sie README.md als Github-kompatibel verwenden möchten, habe ich oft das gleiche Problem. so ist dies eine gute Alternative. Persönlich bevorzuge ich YARD für die Dokumentation meiner Ruby-Code, es ist mächtiger, und tatsächlich vollständig kompatibel mit Rubygems, es ist die bevorzugte Art und Weise.

Geben Sie, dass Ihr Rakefile zu vergrößern:

require "github/markup" 
require "redcarpet" 
require "yard" 
require "yard/rake/yardoc_task" 

YARD::Rake::YardocTask.new do |t| 
    OTHER_PATHS = %w() 
    t.files = ['lib/**/*.rb', OTHER_PATHS] 
    t.options = %w(--markup-provider=redcarpet --markup=markdown --main=README.md) 
end 

nicht (erneuern.das Gemfile) zu bündeln Vergessen