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.
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.
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.
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.
Related
I have a problem :0
At my place of work we have two wiki systems and I have been charged with finding a way of migrating from a MediaWiki to a redmine wiki -- only problem is they use different markup languages (WikiText vs Textile) and a possible solution (Pandoc) only goes the other way :0 Any suggestions on how to do this would be greatly appreciated!!!
The MediaWiki to Redmine Migration Tool (MRMT) has just been released.
It migrates the whole history with the correct user assigned to each revision.
Besides a basic Pandoc translation it also adds some helpful replacements that will very likely be necessary in any migration of that kind.
The development version of pandoc now has a mediawiki reader. It doesn't support all of mediawiki syntax (e.g. templates), and it is not very well tested, but you could try it out.
You would need to install the development version of pandoc from source to do this. Install the Haskell Platform, then follow the instructions here.
(These instructions assume a *nix build environment.)
You will probably want to use some scripting to adjust the result, e.g. making links with title "wikilink" into proper redmine wikilinks. It is easiest to do this at the level of the pandoc AST, rather than in the textile result. The document on Scripting with pandoc on the pandoc website may be of help here.
Another approach is to scrape the HTML your redmine wiki produces, and use pandoc to convert that to textile. This approach typically requires a lot of preprocessing and postprocessing, though.
You could also try using one of the various alternative mediawiki parsers, producing HTML or DocBook and converting that to textile using pandoc.
There are many libraries for transforming markups like reStructuredText and markdown to HTML. I have some users who are familiar with the markup used in Atlassian's Confluence wiki product, which is unfortunately proprietary -- is there any open source compiler for the confluence wiki markup format, or possibly something that would transform it to an intermediate format?
I think Confluence uses the Textile markup format. I have used over the last few years a rails application that used the gem RedCloth to do the transformation, and I could switch between the 2 formats. I never checked if it is complete interchangeable, however.
You could check for yourself if it is sufficient at Try RedCloth.
I need to call some helpers from a Markdown view. Is this somehow a good practice and is generally supported on popular ruby-based Markdown parsers?
No, it isn't. Markdown is a standardized, text-focused, cross-language format and the most of Markdown parsers offers support for the standard syntax.
However, platforms that need advanced features, such as wiki and GitHub, adds custom features. Common features, are tags to generate page TOC based on the document structure.
AFAIK, not BlueCloth nor RDiscount offers built-in support for extensions. You would have to code them yourself before passing the markdown text to processor.
Extending the class to handle new tags or syntax is not a bad idea, but eval'ing inline ruby code from a possibly untrusted source is an absolutely horrible idea!
I am a big fan of doxygen which I have used for years with various languages. In particular, I appreciate its wiki-like ability to include images and run the Graphviz dot generator to have arbitrary inline diagrams from inline DOT code or external files.
RDoc has diagramming support to generate class diagrams using Graphviz but I can't see any way to include arbitrary images or diagrams. Neither does it appear to support building up arbitrary pages like oxygen.
Is there any tool which provides these Doxygen-style features for Ruby?
I have skimmed the Ruby Toolbox list of tools and they all seem to be variants of RDoc.
The most likely solution for me at present seems to be extending Yard.
RDoc will automatically convert urls to html links and urls which point to image files are automatically converted to html images.
As I was told at a Perth Agile Meetup last week, graphviz integration is now available as a branch of yard.
I'm looking for a general purpose syntax highlighting library, to output to html.
It's for use within a ruby app, so a ruby library would be good, but an excellent utility which can be piped in and out of would do
Also needs to guess the appropriate language to highlightsy by itself
HTML/CSS/JavaScript based syntax highlighter solutions are the most popular and work well with different server technologies including Ruby.
SyntaxHighlighter (RECOMMENDED) is here to help a developer/coder to post code snippets online with ease and have it look pretty. It's 100% Java Script based and it doesn't care what you have on your server.
Syntax highlighting library for various languages at Rubyforge.org. Has built-in support for converting source code to syntax-highlighted HTML.
SyntaxHighlighter for WordPress. It allows you to easily post syntax highlighted code all without losing its formatting or making an manual changes.
Prettify. A Javascript module and CSS file that allows syntax highlighting of source code snippets in an html page.
GeSHi - Generic Syntax Highlighter. GeSHi started as an idea to create a generic syntax highlighter for the phpBB forum system, but has been generalised to this project. GeSHi aims to be a simple but powerful highlighting class, with the following goals: (1) Support for a wide range of popular languages (2) Easy to add a new language for highlighting (3) Highly customisable output formats
JUSH is a syntax highlighting component written in JavaScript. It highlights HTML, CSS, JS, PHP and SQL code embedded into each other. Beside syntax highlighting, it provides links to the documentation for all supported languages.
SyntaxHighlighter for Windows Live Writer at CodePlex.com (just in case :)
And here a few blog posts on the subject:
Syntax Highlighting for Ruby Made Very Easy
Syntax highlighting in Ruby
Have you looked at Google's syntax highlighter? I believe SO uses it?
http://code.google.com/p/syntaxhighlighter/
Edit: Actually I believe it is Prettify:
http://code.google.com/p/google-code-prettify/
Some options are:
Syntax - Its really broad, but I think it has some licensing concerns (Syntax is GPL)
Coderay - I use this on my blog, it's pretty limited, but is functional
Ultraviolet which support a ton of languages (anything that textmate can do)
If you are willing to bridge into Python there is Pygments, which supports a ton of languages
Try rouge. It's pure ruby, compatible with pygments, and actively developed.
You might want to take a look at Colorer. It doesn't seem to have bindings for Ruby, but there are for Perl and PHP, maybe one would be able to hack a binding together for Ruby on that basis.
Scintilla can be used with C++ code. I don't know about is there a way to use C++ applications in Ruby.