Documenting an API using Slate - tooltwist/documentation GitHub Wiki

Slate is a great tool for documenting a RESTful API. Slate can be run as a Docker container, avoiding the need to install documentation tools on your desktop machine.

The documentation can be saved as a Github project, and published using the project's GitHub Pages.

The following instructions assume you already have Docker running on your machine. At the time of writing (January 2016) the easiest way to run Docker is by installing Kitematic as part of Docker Toolbox.

This video shows the entire process in two and a half minutes: https://www.youtube.com/watch?v=zx1T7yy28uI

Initial Setup

Create a new repo in Github. For example, named tooltwist/myproject-api-docs.

Start your command line (using Terminal on OS X) and set the following variables accordingly.

 $ GITHUB_ACCOUNT=tooltwist
 $ PROJECT=myproject-api-docs
 $ EMAIL="[email protected]"
 $ NAME="Fred Smith"

Create the Slate project by cutting and pasting these commands into your command line.

cd ~/Development  
git clone https://github.com/tripit/slate.git ${PROJECT}  
cd ${PROJECT}
git remote rm origin  
git remote add upstream https://github.com/tripit/slate.git  
git remote add origin https://github.com/${GITHUB_ACCOUNT}/${PROJECT}.git 
echo done

Create a few nice commands. Cut and paste the entire block below into your command line:

cat > start.sh << END1
docker run -d -p 4567:4567 --name ${PROJECT} -v \$(pwd):/app slate
END1
cat > sync.sh << END2
docker exec ${PROJECT} touch /app/source/index.md
END2
cat > stop.sh << END3
docker rm -f ${PROJECT}
END3
cat > README.md << END4
This project documents the RESTful API provided by it's associated Github project.
See http://${GITHUB_ACCOUNT}.github.io/${PROJECT} for the API documentation.
END4
cat > publish.sh << END5
docker exec -it ${PROJECT} /bin/bash -c "git config --global user.email ${EMAIL}"
docker exec -it ${PROJECT} /bin/bash -c "git config --global user.name \"${NAME}\""
docker exec -it ${PROJECT} /bin/bash -c "rake publish"
END5
chmod +x start.sh stop.sh sync.sh publish.sh
echo done

Publish to your Github project.

git add .
git commit -m "Initial setup"
git push -u origin master  
echo done

Prepare the Docker container, if this hasn't been done previously for another documentation project.
```
$ docker build -t slate .
```

Editing the Documentation

Start the Docker container
```
$ ./start.sh  
```
Viewing the documentation.

Get your Docker IP address using env | grep DOCKER.
Open the documentation in your browser at (for example): http://192.168.99.100:4567/

Update the documentation.

Edit /app/source/index.md with your favorite editor. A description of the markup commands can be found here.
Refresh your browser page (Cmd-R) to see the updates.
If the changes aren't immediately visible, you might need to run ./sync.sh.

Save your changes to Github using normal git commands.

Publishing your Documentation

To publish to the github page of your repo, commit all your changes, then run ./publish.sh.

Once complete, and after a small delay while Github processes the commit, your API documentation will be available as a Github Page.

    open http://${GITHUB_ACCOUNT}.github.io/${PROJECT}

Trouble Shooting

When you are publishing, the error message 'Directory not clean', means you probably forgot to commit all your changes. Run git status to check.
If you enter a github password incorrectly during the initial publish, subsequent publishing may also fail. The solution is to remove the build directory - rm -rf build.
To upgrade Slate, follow these instructions. Note that a remote named 'upstream' will not need to be defined as it was already defined above.