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
Related
I've written some using documentation for a ruby gem. I'm using yard to generate the ruby gem reference documentation from the ruby source, and I want yard to work with this other markdown documentation.
I've written the documentation within the gitlab wiki which uses the same markdown as github and all the links to anchors work.
When I use yard to generate html from the markup two things go wrong. The first is the links didn't work because in the markdown references to other files didn't include an extension e.g. [Getting Started] (Introduction#getting-started) which worked in the wiki but yard needs a [Getting Started] (Introduction.html#getting-started). I was able to get around this by writing a rewrite rule in the .htaccess file.
The second issue is harder. The wiki generated anchors to headings are like as above, whereas yard anchors are: Introduction.html#Getting_Started
I've tried sorting out the case issue by adding [NC] in the .htaccess file but this didn't help. Plus there is the issue of the "-" changing to a "_".
The relevant bits from my .yardopts file in relation to my question are:
--markup markdown
--markup-provider redcarpet
My question is:
Is the structure of the generated anchors due to either the choice of markup or markup provider? I'm confused by these terms and I've not been able to find useful documentation about them.
I've got the github-markup gem installed and I've tried replacing markdown with github-markup, and that didn't work, then I tried replace redcarpet with github-markup but that also doesn't work.
I keep searching for documentation to try and understand what I'm doing here without gaining any clarity thus the clutching at straws.
Standard ruby on rails project has README.rdoc.
Many github rails projects have README.md.
What is the difference?
Answer fragment from another deleted Stack Overflow question by kiddorails:
RDoc is a fantastic tool which enables the automatic generation of formatted HTML containing our documented code.
For example, most of gems on RubyGems fetch documentation and compiles them to give the resultant rdoc.
If your project doesn't have README.md, GitHub may parse README.rdoc to display details. If it has both, it will use README.md, silently ignoring rdoc. I usually have both, README.md for Github, and README.rdoc for RDoc documentation on RubyGems.
RDoc - is a RubyGem which produces HTML and command-line documentation for Ruby projects. RDoc includes the rdoc and ri tools for generating and displaying documentation from the command-line.
Digging Deeper Rdoc
Markdown also known as md is a plain text formatting syntax5 designed so that it can optionally be converted to HTML using a tool by the same name. Markdown is popularly used as format for readme files, or for writing messages in online discussion forums, or in text editors for the quick creation of rich text documents.
Github's Markdown
Github's Markdown basics
RDoc is a markup language. Markdown is a different markup language. HTML is yet another markup language. Any of those can be used to markup text, and all of those are supported by various code-browsing tools including but not limited to GitHub.
I wrote a Javascript (jQuery) plugin. Now I want to write a documentation site for it. Is there a good tool to create such a site out of some offline file formats or works like a CMS?
I know this answer has been asked before, but the last answers are from 2011. Is there anything new that does an awesome job in writing documentation?
There are a few new tools for generating websites or blogs from code/directory.
Bootstrap v3 just switched to jekyll for documentation. jekyll knows how to process Markdown or Liquid (markdown flavours)
Grunt.js is also used for all sorts of automated task. One of these being documentation generation. Search their plugin list for doc
assemble.io is another tool for generating documentation pages
I'll extend if I bump into others. I am not sure if this is exactly what you need, but they are general purpose so I am sure a jQuery plugin can fit in.
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.