HOWTO.md

---

Table of Contents

• About
• Local Setup
  • Installation
  • Running a Local Gitbook
  • Running a Build
• Publishing the docs
  • Travis CI Publishing
  • Manual Publishing
• The API Reference Section
  • Generating the Section
  • Picking up Changes

---

About

This is a documentation project for Nakadi. It's based on Gitbook and publishes content to Github Pages.

Gitbook/Github pages want to use README.md as part of the book, so the howto is here.

Local Setup

Installation

You'll need to install npm and java 8 to get going. Once you've got those, clone the project, cd to the project's home directory and run:

npm install gitbook-cli --save-dev
npm run docs:prepare

This will set up gitbook and gitbook-cli locally in the project.

Running a Local Gitbook

You can start a local server on http://localhost:4000 that will watch for changes:

npm run docs:watch

Running a Build

If you just want to run a build you can run:

npm run docs:build

This will update the pages content in the _book directory.

Publishing the docs

Travis CI Publishing

Docs are published to github pages using Travis CI.

Travis has an envar called GH_PAGES_TOKEN set with a personal access token that allows it to push to the gh-pages branch. The token is also encrypted in .travis.yml files env.global area using the travis cli command:

gem install travis
travis encrypt -r zalando-nakadi/nakadi-manual GH_PAGES_TOKEN=${GH_PAGES_TOKEN} --add

The build step requires both NPM and JDK 8 - to allow Travis to use both and set JDK 8 via its jdk_switcher command, the setup uses the trusty Ubuntu distribution (otherwise the build will fail as JDK8 is not the default in Travis).

The publishing script run by Travis is gh_pages_publish.sh. The script restricts publishing to updates against the master branch - pull requests and other branches will only result in a build.

Manual Publishing

You can force a manual publish:

npm run docs:publish

For this to work it will need a GH_PAGES_TOKEN envar set with a personal access token.

The API Reference Section

Generating the Section

This section is generated from a copy of the Open API definition. The definition files are kept in ./docs/api-spec-oai and the publishing code targets the symlinked file nakadi-oai-current.yaml. Eventually it's hoped the build will run directly from the Nakadi project's yaml file, but for now there's a managed copy locally.

Generation uses the swagger2markup project to convert the yaml to markdown and place the output into the api-spec-generated directory. The swagger2markup configuration is in the ./bin directory and the additional reference text is in the api-spec-extensions directory. The swagger2markup jar files are checked in source to make it easy to run a build.

Picking up Changes

The npm run docs:watch will not automatically pick up changes to the Open API files. To have the changes seen, run:

npm run docs:genapi