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.
Related
I am trying to automate documentation using markdown compatible wiki without having a separate server.
I have ruby code with yard compatible documentation. If I run
yard doc, it generates html files in ./doc directory.
Would it be possible to generate .md files from the code using yard? So that I can simply add these files to GitLab or GitHub wiki or other markdown supported wiki?
Sorry if the question is repeated.
Stumbled on this question doing my initial research, but haven't found an answer here. It may sound strange, that some people want to convert documentation no to html, but to markdown instead.
But there are plenty of software that can't render HTML, but works with markdown.
I have developed rdoc plugin to do that.
https://github.com/skatkov/rdoc-markdown
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.
I saw this related question about publishing toolchain but I know many people did lot of work to produce publishing toolchains recently.
One great example I found is this project from akosma.
Avdi Grimm shared his work with org-mode in this project
I know there are (should be) many others.
What I'm looking for, is a publishing toolchain with
asciidoc / markdown / textile / org-mode or latex input. I don't want xml input
pdf AND html output, epub output is not a requirement for me.
What I can
author templates in latex / html / css / js. again, no xml.
read and write ruby and shell scripts
Take a look at asciidoc, this is what O'Reilly has started using and it is a refreshing break from DocBook. I use asciidoc, the tools and support leaves a little to be desired, but there are people working to create better alternatives (that don't involve Python and the existing Docbook pipeline).
Check out this: https://github.com/runemadsen/asciidoc
EDIT 1/6/13: You also really need to check out AsciiDoctor. Dan Allen from RedHat has been spending a lot of time on this particular package and Ryan Waldron. I expect great things from AsciiDoctor as it is starting to emerge as a foundation for a bunch of important AsciiDoc documentation efforts.
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.
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.