CODEWITHSUNDEEP
rubymarkdowndocumentation-generationpython-sphinxrestructuredtext
user1026169
user1026169

Reputation: 5845

Ruby equivalent of Sphinx documentation generator?

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.

Upvotes: 6

Views: 3862

Answers (3)

Paul Nerger
Paul Nerger

Reputation: 11

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.

Upvotes: 0

Tom
Tom

Reputation: 1007

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.

Upvotes: 3

Kevin Horn
Kevin Horn

Reputation: 4295

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.

Upvotes: 8

Related Questions