6

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.

mzjn
  • 48,958
  • 13
  • 128
  • 248
user1026169
  • 5,345
  • 5
  • 21
  • 35
  • For documentation or for other purposes? – Niklas B. Feb 21 '12 at 16:01
  • Of everything Sphinx does, http, pdf & epub are the ones that interest me most. – user1026169 Feb 22 '12 at 03:54
  • It's not clear whether you are looking for a tool that does what Sphinx does, but for Ruby code, or are looking for a tool specifically written in Ruby. – Kevin Horn Mar 21 '12 at 16:52
  • i'm looking for a tool written in Ruby – user1026169 Mar 22 '12 at 19:22
  • 2
    What aspect of ruby do you need for your documentation generation process? There's nothing quite like Sphinx in Ruby, but it's unclear to me what problem you're trying to solve by having an alternate implementation of Sphinx in a different language. – tychoish Mar 27 '12 at 14:54
  • thanks for the direct answer. if you change it to answer and not a comment then i can upvote it. i am more familiar with the ruby tool chain, and ruby programs of this type tend to rely on markdown which i also prefer. – user1026169 Mar 27 '12 at 15:22

3 Answers3

8

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.

Kevin Horn
  • 4,167
  • 28
  • 30
3

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.

Tom
  • 1,007
  • 12
  • 13
0

Another couple of options would be to use Middleman which is a static site generator that accepts either Kramdown or Markdown as input.

There are also frameworks that are designed specifically for technical documentation that use Middleman (both of which are on GitHub) including lord/slate and pnerger/dpslate (the later is a fork of the former and provides some enhancements that were not appropriate for pulling). The Slate format provides a format for documentation that includes many of the features of Sphinx with some additional enhancements. It features a three-pane view of a document which includes an automatically generated Table of Contents, a Main center body, and then sample code panel to the right. Like Sphinx the sample code has syntax highlighting.

Paul Nerger
  • 11
  • 2