ContextQMD
Back to Predictionio

Contribute Documentation

docs/manual/source/community/contribute-documentation.html.md

0.14.06.2 KB
Original Source
<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->

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.

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:

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

Starting the Server

Start the server with:

$ bundle exec middleman server

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

Building the Site

Build the site with:

$ 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:

---
title: Page Title
---

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

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/).

md
[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.

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:

Code Blocks

Fenced code blocks are created using the <code>```language</code> format.

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

Code Tabs

Code tabs use the following HTML format:

html
<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:

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

Important Files

DescriptionFile
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

Versions

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.

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:

$ 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:

Checking the Site

WARNING: The check rake task is still in beta however it is extremely useful for catching accidental errors.

bash
$ 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.