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.
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.
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.
WARNING: OS X users you will need to install Xcode Command Line Tools with: $ xcode-select --install
first.
You can install everything with the following commands:
$ cd docs/manual $ gem install bundler $ bundle install $ npm install -g bower $ bower install
Start the server with:
$ bundle exec middleman server
This will start the local web server at localhost:4567.
Build the site with:
$ bundle exec middleman build
Please follow this styleguide for any documentation contributions.
View our Sample Typography page for all possible styles.
The main heading h1
is derived from the title data attribute:
--- title: Page Title ---
Start other headings with h2
. Prefer the ## Heading
format in Markdown.
Internal links:
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/)
.
[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 should be exactly 900px wide. Chrome Window Resizer is an excellent extension for browser resizing.
WARNING: OS X users please Disable Shadows before taking a screenshot.
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:
<img src="/images/path/to/image.png" alt="Image" class="static" />
Fenced code blocks are created using the ```language format.
A example of each language is available on our Language Samples page.
Code tabs use the following HTML format:
<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.
You can hide a page from the sitemap.xml
file by setting the pages Frontmater like this:
--- title: Secret Page hidden: true ---
Description | File |
---|---|
Left side navigation. | data/nav/main.yml |
Main site layout. | source/layouts/layout.html.slim |
Custom Markdown renderer based on Redcarpet. | lib/custom_renderer.rb |
Custom TOC helper. | helpers/table_of_contents_helpers.rb |
Various site wide versions are defined in data/versions.yml
and embedded with ERB like <%= data.versions.pio %>
.
NOTE: Files must end with a .erb
extension to be processed as ERB.
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:
$ 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):
$ git push apache livedoc
You can check the progress of each build on Apache's Jenkins:
WARNING: The check rake task is still in beta however it is extremely useful for catching accidental errors.
$ 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.
Documentation is under a Apache License Version 2.0.