Strictly speaking, the only tools required to craft documentation are the standard development tools. You'll need jekyll to generate the site for preview purposes, but it's not strictly required.
If you encounter the following error:
runner.rb:365:in 'require_program': program version required (Commander::Runner::CommandError)
...
custom_require.rb:36:in 'gem_original_require': no such file to load -- json (LoadError)It means that the json gem is missing: gem install json should solve the problem...
###Windows
- You'll need to have Python 2.7.6 installed
- You'll need to have Ruby 1.9.3 installed
git clone git@github.com:Jasig/cas.git cas.sitegit checkout gh-pages- Change documentation as necessary
git push --set-upstream origin gh-pages
The changes should be almost immediately available at http://jasig.github.io/cas/.
kramdown is the markdown engine used by the site. You'll need to download kramdown before attempting to run the build. See documentation for platform-specific details.
Generating the site to preview changes before commit is encouraged. Install jekyll and execute the following command from the documentation root directory:
jekyll build --safeBrowse to the output directory _site in a browser to preview the generated site.
Alternatively, you may also invoke the documentation build script:
build.[bat|sh]The build will auto-generate tags for section headers.
The documentation site is composed of the following blocks:
- Each version of the documentation is moved to an appropriately named folder (i.e.
4.0.0) - Each version contains its own version of the sidebar TOC. While the TOC is designed to be included in the default
Jekyll layout, the site will load the appropriate version of the TOC on
jasig.github.io/cas. - The
currentfolder contains the version of the documentation in development - Developer-related documentation is hosted at the root under the
developerdirectory - The root
index.htmlalways points to thecurrent\index.htmlpage. - Page titles are auto-calculated based on the first
h1element on the page, followed by the version of the documentation (i.e.Service Management (x.y.z))
If you have trouble getting jekyll to build, try the following:
- Make sure python is included in your $PATH
- If you are receiving unicode incompatibility errors, try the command
chcp 65001 - There exists a bug with Jekyll 1.4.3 that does not properly utilize file separators. You may have to downgrade to Jekyll 1.4.2 or upgrade to the next 2.x release.