This template allows you to document your Torch package using Github Flavoured Markdown, and automatically generate nicely styled HTML with automatic table of content, to be distributed along with the source and published online.
Four live examples:
bundler, which ensures that all the Ruby packages needed are automatically installed in their adequate version:
gem install bundler
Jekyll, which does the site building and uses Redcarpet to do the rendering from Github Flavoured Markdown to HTML:
gem install jekyll
From the root of your repository, in the master branch:
git remote add template https://www.github.com/jucor/torch-doc-template
git fetch template
git merge -X ours template
This will create a folder doc/src, that you can edit, and doc/html, that will be automatically built by Jekyll and that you will then publish.
After editting your Markdown files in doc/src, you need to convert it to HTML locally, with automatic Table of Contents, styles and layouts, using Jekyll:
cd doc/src
bundle exec jekyll build --destination ../html
Your users can now browse your documentation with their browser, opening [doc/src/index.html], and you can distribute it along with your package.
Optional but convenient: while you edit, Jekyll can dynamically build your pages, refresh them, and serve them to http://localhost:4000:
cd doc/src bundle exec jekyll serve --destination ../html --watch
It is recommended to have the pages published online, too. If your project is on Github, using Github Pages facility is easy.
Note: even though Github Pages runs a version of Jekyll on their server, it forbid plugins, i.e. no automatic Table of Contents, and would not allow you to distribute the HTML rendering of your documentation along with your source for local browsing. This is why this template recommends to use your own Jekyll locally and only push HTML pages to GH-Pages.
Create a branch named gh-pages, where Github Project Pages for content. The git subtree command moves all files from doc/html to the root of the gh-pages branch.
git subtree split --prefix doc/html --branch gh-pages
Now, everytime you have modified doc/src, updated locally the doc/html with Jekyll, and committed both to your master branch, you just:
Commit to your master branch the changes you just made:
git commit -a -m "Regenerate HTML pages"
Update the gh-pages with only the HTML part, automatically moved to the root, by:
git checkout gh-pages
git merge -X theirs -X subtree=doc/html master
And push online:
git push -u origin gh-pages
Your files will now be accessible at http://yourlogin.github.io/yourrepository.
To modify your documentation:
Change index.markdown and add any markdown or HTML files:
Important: Jekyll only converts and adds ToC to Markdown files that start with the header:
--------
title: My title
layout: doc
--------
If your Markdown files are not converted, make sure that you have added this header at the beginning. HTML files do not need this header.
_layouts: contains the template rendering, including the call to the table of contents plugin.
Gemfile: specifies which version of Jekyll and redcarpet to use, to ensure maximum rendering reproducibility.