Ruby equivalent of Sphinx documentation generator?

Question

There are several good document generators in Ruby, such as Yard, rDoc, even Glyph. The fact is that Sphinx makes sites, PDF, epub, LaTex ... etc. He does all this in a restructured text.

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

Answer 1

Starting with version 1.0, Sphinx had the concept of "domains", which is a way to mark up code entities (such as method calls, objects, functions, etc.) from lannguages ​​other than Python and / or C.

There is a ruby domain , so you can just use Sphinx. The only thing you were missing (I think) was the ability of Sphinx to automatically create documentation from the source using the autodoc extension, which works specifically with Python code.

Answer 2

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

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

It generates static HTML, so the resulting documentation is easy to post and does not have much effect on the load on your server.

To see this in action, open wpmvc.org .

Answer 3

Another pair of options is to use Middleman, which is a static site generator that accepts Kramdown or Markdown as input.

There are also frameworks that are specifically designed for technical documentation that use Middleman (both of which are on GitHub), including lord / slate and pnerger / dpslate (the later version is the plug of the first and provides some improvements that are not suitable for pulling) . The Slate format provides a documentation format that incorporates many of the features of Sphinx with some additional enhancements. It has a three-panel view of the document, which includes an automatically generated table of contents, the main center, and then a sample code panel on the right. Like Sphinx, the sample code has syntax highlighting.