31 July 2015

The reference documentation for R.NET is still at R.NET on codeplex. While adequate, the Codeplex seems not to add features, so it is time to move to something else. Keeping documentation and code nearby is a good idea, so GitHub pages comes to mind. I rather like Markdown, so using Jekyll makes some sense. For better or worse, there are quite a few options to generate documentation, whether using Jekyll or not. This post lists resources I found of interest.

Review

Resources

Historically, Jekyll seems to have been oriented towards blog sites (by nature or by prevalent usage). Some sites that are of interest to manage documentation via Jekyll:

Blog posts:

Other documentation sites:

More for a blog site:

Observations

After following the GitHub and jekyll docco. I quickly got issues running sites on my machine. Not impressed by what looks like the equivalent of null reference exceptions, including on this very present site. Seems to work when pushed on GitHub.

$~/src/github_jm/jmp75.github.com$ jekyll serve Configuration file: /home/per202/src/github_jm/jmp75.github.com/_config.yml Source: /home/per202/src/github_jm/jmp75.github.com Destination: /home/per202/src/github_jm/jmp75.github.com/_site Generating... Conversion error: Jekyll::Converters::Markdown encountered an error converting '_posts/core-samples/2011-12-29-jekyll-introduction.md/#excerpt'. Conversion error: undefined method `gsub' for nil:NilClass jekyll 2.4.0 | Error: undefined method `gsub' for nil:NilClass