search

getchip / CHIP-Docs

User Manual and Documentation of Next Thing Co's C.H.I.P.
http://docs.getchip.com/chip.html
Other
36 stars 47 forks source link

readme

Next Thing CHIP Documentation

This is a source repo for documentation. If you want to see it as a website, you'll need to render it to HTML. Read on!

Quick Start

git clone https://github.com/NextThingCo/CHIP_Pro-Docs
cd CHIP_Pro-Docs
bundle install
bundle exec middleman server

Go to your browser and visit http://localhost:4567 to view the docs.

If this fails, read on!

Intro

All documentation is written in markdown and staged on github pages. Published documentation is viewable on the github pages.

If you want to add or modify a document, add your markdown file to the includes directory and make a pull request. You can use Github markdown or regular markdown.

Each include represents a top-level topic in the left-hand navigation if it is in the list of includes in index.html.

Note: If you view the files in the include/ directory here on github, the image links appear broken. This is to be expected because these pages have yet to be rendered into a viewable state.

Uses the Slate Documentation Generator

This repo is forked from Slate. Read the docs on the original Slate repo wiki if you want all the details. There are also some sample docs worth perusing.

Here's the crux of the matter, though:

Prerequisites

You're going to need:

Ubuntu 14.04 LTS

Install the following packages, then jump to the Preview section.

sudo apt-get install git ruby-dev
sudo gem install bundler
cd 
git clone git@github.com:NextThingCo/DIP-Docs.git
cd DIP-Docs
bundle install

Getting El Capitan to Behave

Installing on El Capitan (OS X 10.11) can be difficult. Once you clone the directory, you may need to cd to the chipdocs directory, then run the command bundle install. If you get errors when you try to run ./deploy.sh after that, try bundle update to install the bundler, and then try ./deploy.sh again.

There may be some other black magic involved in getting it working on El Capitan, including:

brew install ruby
sudo gem install therubyracer -v '0.12.2'
sudo gem install libv8 -v '3.16.14.13' -- --with-system-v8

or perhaps even adding -n /usr/local/bin to the end of those last two items. I had to fumble around with a lot of various suggestions on the internets to finally get this working on El Capitan, so it is hard to say exactly which one fixed it. The last command I tried before it worked was bundle update, so I'd try that first!

Preview

If you want to preview your changes to the documents in a browser before you make a pull request or push changes, navigate to the chipdocs/ directory, and use the middleman server to render and serve the documentation in HTML. The terminal will tell you the URL to use to check out the docs.

bundle install
bundle exec middleman server

Publish

The normal Slate workflow requires that changes to the master branch be commited and pushed. Then, the deploy.sh script can be run locally to render HTML, push changes to the gh-pages branch, and made live. We've modified the workflow so an external script monitors this repo, renders any changes to the HTML, then merges with the other "-Docs" and "landingpage" repositories in this organization to create the "masterdocs" repository. Ultimately it all ends up at docs.getchip.com