Ruby equivalent of Sphinx documentation generator?

Question

Ruby has a few good document generators like Yard, rDoc, even Glyph. The thing is that Sphinx does websites, PDF's, epub, LaTex...etc. It does all these things in restructuredtext.

Is there an alternative to this in the Ruby world? Maybe a combination of programs? If I could use Markdown as well that would be even better.

Answer 1

Since version 1.0, Sphinx has had a concept of "domains" which are ways of marking up code entities (like method calls, objects, functions, whatever) from lannguages other than Python and/or C.

There is a ruby domain, so you could just use Sphinx itself. The only thing you would be missing (I think) is Sphinx's ability to create documentation from source automatically using the autodoc extension, which works specifically on Python code.

Answer 2

If you want to use Markdown, you might check out JDoc, which is a very simple, Ruby-based documentation framework that lets you use widely-supported markup and put it under source control. It lets you edit the documentation in your text editor of choice, and it supports:

• Markdown or Textile
• syntax highlighting
• easy internal links
• a hierarchical documentation structure (useful for large projects)
• customizable styling and structure (but it looks nice out of the box, too)

It generates static HTML, so the resulting documentation is easy to host and doesn't have much of an impact on your server load.

To see it in action, check out wpmvc.org.