Using yard to work with markdown files - ruby

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.

Related

yard to generate markdown files instead of html?

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

Extending redcarpet for Jekyll?

I've found this post Jekyll, modify the way some html tags are rendered
Which does explain how to extend redcarpet itself.
But what else needs to be done in order to get such extension to work?
What name does the extension correspond to in the _config.yml ?
Do I need to include anything in my gem file?
If I simply change "markdown: redcarpet" to "markdown: RedcarpetMod" github pages will send a main telling me that there were syntax errors in the first markdown file it tries to process.
Your stumbling block here is GitHub pages — the answer given by #cyrusza in the question you've linked works fine (I am using it to modify redcarpet's rendering on one of my sites). GitHub pages, however, runs in safe mode which means that it does not allow custom plugins at all and instead only supports a few specific plugins.
Check the Plugins page in the Jekyll documentation for the note about safe mode (in the first blue box), and the GitHub Pages help page about plugins for the list of which plugins are allowed.

What is the difference between rdoc and md?

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.

Generating Jekyll Pages from Liquid and Markdown instead of HTML

I'm using a slightly modified version of the example generator from Jekyll's plugins section of their docs (https://github.com/mojombo/jekyll/wiki/Plugins#generators) and I'm curious if there is any way to parse a liquid/markdown file instead of a plain HTML files from the example?
Notice this line:
self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
That category index.html file is the target file which will be used in generated files. My goal is to be able to pass an object to a my generator from my _config file which I can then use to build a bunch of pages from a .markdown file instead. Does anyone know if this is possible or have any recommendations for achieving this? I looked into the Kramdown lib that's used to parse markdown internally, and I'm not opposed to invoking it myself if I have to, just wasn't sure if I was going deeper than I needed to for something that should be so simple. The API for the Page object which my generator creates is here: http://ruby-doc.org/gems/docs/j/jekyll-0.12.0/Jekyll/Page.html
Thanks a ton,
- Keith
You can generate virtually any format you want, from virtually any data source you want, in a generator, because you're writing straight Ruby with full access to the Jekyll object model. For example, here's a generator I put together the other night that fetches GitHub commits during jekyll build.
The question I would be asking is this:
Do I need a plugin to accomplish this?
If so, do I need a formal generator plugin as discussed in the Jekyll docs?
Or should I subclass, monkey-patch, or otherwise change the behavior of the built-in generator?
Also, the differences between Markdown and HTML files in this context (where you control 100% of what gets generated) are mostly nominal. read_yaml IIRC will actually read the front matter from both, so that shouldn't be an issue.

Ruby equivalent of Sphinx documentation generator?

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.

Resources