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.
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'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.
I run a blog using Jekyll, and thought I'd settle with Redcarpet markdown interpreter as it's developed and used by GitHub.
Well, I just happened to come across a bug, went to checkout the issues, and found this.
Maintainer says, "As you probably have noticed (har har har har) I don't have time to maintain Redcarpet anymore. It's not a priority for me (I find Markdown thoroughly boring) and it's not a priority for GitHub, because we no longer use it in production."
So...
Is there a good Ruby markdown interpreter (i.e. actively developed, with sane syntax) that I can use with Jekyll (& pygments)?
Even better, a markdown interpreter with syntax similar to (or at least close to) GitHub Flavored Markdown?
https://github.com/vmg/redcarpet Redcarpet is very actively developed and was updated about 8 hours ago (at the time of this writing.)
For "flavoring" your Markdown: https://rubygems.org/gems/github-markdown
To convert Markdown to HTML:
GitHub::Markdown.render_gfm("# Header")
To render within Rails:
GitHub::Markdown.render_gfm("# Header").html_safe
Want syntax highlighting?
https://github.com/simplabs/highlight
https://alphahydrae.com/2013/01/markdown-views-in-rails/
Cheers!
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 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.