How to Write Documentation

You can help improve the Apache PredictionIO documentation by submitting tutorials, writing how-tos, fixing errors, and adding missing information. You can edit any page live on GitHub by clicking the pencil icon on any page or open a Pull Request.

Branching

Use the livedoc branch if you want to update the current documentation.

Use the develop branch if you want to write documentation for the next release.

Installing Locally

Apache PredictionIO documentation uses Middleman and is hosted on Apache.

Gems are managed with Bundler. Front end code with Bower.

Requires Ruby 2.1 or greater. We recommend RVM or rbenv.

You can install everything with the following commands:

1
2
3
4
5

$ cd docs/manual
$ gem install bundler
$ bundle install
$ npm install -g bower
$ bower install

Starting the Server

Start the server with:

1

$ bundle exec middleman server

This will start the local web server at localhost:4567.

Building the Site

Build the site with:

1

$ bundle exec middleman build

Styleguide

Please follow this styleguide for any documentation contributions.

Text

View our Sample Typography page for all possible styles.

Headings

The main heading h1 is derived from the title data attribute:

1
2
3

---
title: Page Title
---

Start other headings with h2. Prefer the ## Heading format in Markdown.

Links

Internal links:

• Should start with / (relative to root).
• Should end with / (S3 requirement).
• Should not end with .html.

Following these rules helps keep everything consistent and allows our version parser to correctly version links. Middleman is configured for directory indexes. Linking to a file in sources/samples/index.html should be done with [Title](/sample/).

1
2
3
4
5
6

[Good](/path/to/page/)

[Bad](../page) Not relative to root!
[Bad](page.html) Do not use the .html extension!
[Bad](/path/to/page) Does not end with a /.

Images

Images should be exactly 900px wide. Chrome Window Resizer is an excellent extension for browser resizing.

Images should only show the relevant tab/terminal. Hide any additional toolbars.

Images will automatically scale by default. If you want an image to remain a set size you can use a raw HTML tag like this:

1

<img src="/images/path/to/image.png" alt="Image" class="static" />

Code Blocks

Fenced code blocks are created using the ```language format.

A example of each language is available on our Language Samples page.

Code Tabs

Code tabs use the following HTML format:

1
2
3
4
5
6
7
8

<div class="tabs">
  <div data-tab="Tab Title" data-lang="language">
    Markdown, code blocks, or HTML is OK inside a tab.
  </div>
  <div data-tab="Second Tab" data-lang="optional">
    ...
  </div>
</div>

You can see an example of this on our Tab Samples page.

SEO

You can hide a page from the sitemap.xml file by setting the pages Frontmater like this:

1
2
3
4

---
title: Secret Page
hidden: true
---

Important Files

Versions

Various site wide versions are defined in data/versions.yml and embedded with ERB like <%= data.versions.pio %>.

Going Live

For Apache project committers, pushing to the livedoc branch of PredictionIO ASF git will update http://predictionio.apache.org in about 10 minutes.

Make sure the apache.org remote is attached to your predictionio repo, and if not, add it:

1
2

$ git remote -v
$ git remote add apache https://gitbox.apache.org/repos/asf/predictionio.git

Then, push the livedoc branch. (It will be published and synced with the public GitHub mirror):

1

$ git push apache livedoc

You can check the progress of each build on Apache's Jenkins:

• build-site
• publish-site

Checking the Site

1
2

$ bundle exec middleman build
$ bundle exec rake check

The rake check task parses each HTML page in the build folder and checks it for common errors including 404s.

License

Documentation is under a Apache License Version 2.0.