[Documentation] Build documentation in Travis CI

- Install docmaker and its dependencies
- Use docmaker to build documentation and publish to GitHub pages
- Remove unused directives and update Travis CI config
- Closes papyros#128

.gitignore

@@ -6,3 +6,7 @@ tests/tst_material
 build
 *.qmlproject.user*
 *~
+
+deploy_key
+deploy_key.pub
+documentation/ditaxml

.travis.yml

@@ -6,7 +6,7 @@ install:
   - sudo add-apt-repository -y ppa:beineri/opt-qt532
   - sudo apt-get update
   - sudo apt-get -y install qt53declarative
-  - sudo apt-get -y install pep8 pyflakes
+  - sudo apt-get -y install pep8 pyflakes python python-pip
   - sudo apt-get -y install qt53quickcontrols qt53graphicaleffects
   - sudo apt-get -y install qt53tools
 
@@ -17,11 +17,27 @@ before_script:
   - qmake
   - sudo make install
   - popd
+  - git clone git://github.com/papyros/docmaker.git
+  - sudo pip install -r docmaker/requirements.txt
+  - export PATH=$PATH:$(pwd)/docmaker
 
 script:
   - source /opt/qt53/bin/qt53-env.sh
   - qmake
   - make check
+  - ./build_docs.sh
+
+after_success:
+  - ./deploy.sh
 
 notifications:
   slack: papyros:Z7PeY2Y4mh0GWPoypZZNLd3D
+
+# The encryption label is the unique key used in the environment
+# variables set up when calling `travis encrypt-file` on the SSH key
+env:
+  global:
+    - ENCRYPTION_LABEL="a0d7d9cd7ef9"
+    - GIT_NAME="Travis CI"
+    - GIT_EMAIL="[email protected]"
+    - SOURCE_BRANCH="develop"

CHANGELOG.md

@@ -14,6 +14,7 @@ QML Material CHANGELOG
  * [RadioButton] Improve selection support
  * [Demo] Update radio button demo with grouping
 
+
 ### Version 0.0.6 (April 16, 2015)
 
  * Add a ProgressCircle component following the Google spec
@@ -50,6 +51,7 @@ QML Material CHANGELOG
 
 
 ### Version 0.0.4 (February 20, 2015)
+
  * Hide the CSD window controls when client-side decorations are disabled
  * Improve the dialog component to better follow Material Design
  * Add the Material Design Checkbox component

build_docs.sh

@@ -0,0 +1,7 @@
+#! /bin/bash
+
+cd documentation
+rm -r ditaxml html
+
+qdoc material.qdocconf
+docmaker.py ditaxml html

deploy.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+set -e
+
+if [ -n "$TRAVIS_BUILD_ID" ]; then
+    # When running on Travis we need to use SSH to deploy to GitHub
+    #
+    # The following converts the repo URL to an SSH location,
+    # decrypts the SSH key and sets up the Git config with
+    # the correct user name and email (globally as this is a
+    # temporary travis environment)
+    #
+    # Set the following environment variables in the travis configuration (.travis.yml)
+    #
+    #   DEPLOY_BRANCH    - The only branch that Travis should deploy from
+    #   ENCRYPTION_LABEL - The label assigned when encrypting the SSH key using travis encrypt-file
+    #   GIT_NAME         - The Git user name
+    #   GIT_EMAIL        - The Git user email
+    #
+    echo SOURCE_BRANCH: $SOURCE_BRANCH
+    echo ENCRYPTION_LABEL: $ENCRYPTION_LABEL
+    echo GIT_NAME: $GIT_NAME
+    echo GIT_EMAIL: $GIT_EMAIL
+
+    if [ "$TRAVIS_BRANCH" != "$SOURCE_BRANCH" ]; then
+        echo "Travis should only deploy from the SOURCE_BRANCH ($SOURCE_BRANCH) branch"
+        exit 0
+    else
+        if [ "$TRAVIS_PULL_REQUEST" != "false" ]; then
+            echo "Travis should not deploy from pull requests"
+            exit 0
+        else
+            ENCRYPTED_KEY_VAR=encrypted_${ENCRYPTION_LABEL}_key
+            ENCRYPTED_IV_VAR=encrypted_${ENCRYPTION_LABEL}_iv
+            ENCRYPTED_KEY=${!ENCRYPTED_KEY_VAR}
+            ENCRYPTED_IV=${!ENCRYPTED_IV_VAR}
+            REPO=${REPO/git:\/\/github.com\//git@github.com:}
+
+            # The `deploy_key.enc` file should have been added to the repo and should
+            # have been created from the deploy private key using `travis encrypt-file`
+            openssl aes-256-cbc -K $ENCRYPTED_KEY -iv $ENCRYPTED_IV -in deploy_key.enc -out deploy_key -d
+
+            chmod 600 deploy_key
+            eval `ssh-agent -s`
+            ssh-add deploy_key
+
+            git config --global user.name "$GIT_NAME"
+            git config --global user.email "$GIT_EMAIL"
+        fi
+    fi
+fi
+
+REPO=$(git config remote.origin.url)
+TARGET_BRANCH=gh-pages
+SOURCE_DIR=documentation/html
+
+if [ ! -d "$SOURCE_DIR" ]; then
+  echo "SOURCE_DIR ($SOURCE_DIR) does not exist, build the documentation before deploying"
+  exit 1
+fi
+
+REPO_NAME=$(basename $REPO)
+TARGET_DIR=$(mktemp -d /tmp/$REPO_NAME.XXXX)
+REV=$(git rev-parse HEAD)
+git clone --branch ${TARGET_BRANCH} ${REPO} ${TARGET_DIR}
+rsync -rt --delete --exclude=".git" $SOURCE_DIR/ $TARGET_DIR/
+cd $TARGET_DIR
+git add -A .
+git commit --allow-empty -m "Documentation built from commit $REV"
+git push $REPO $TARGET_BRANCH

documentation/material.qdoc

@@ -2,3 +2,4 @@
     \qmlmodule Material 0.1
     \title Material Design UI components
 */
+This implements Material Design for QtQuick.

documentation/material.qdocconf

@@ -1,16 +1,16 @@
 project = Material
 url = http://developer.ubuntu.com/api/ubuntu-12.10/qml/mobile/
-description = Material Design for QtQuick Documentation
+description = Material for QtQuick
 sourcedirs = ./
 sourcedirs += ../modules/Material/
 sourcedirs += ../modules/Material/ListItems
 exampledirs += snippets
 imagedirs = images
 sources.fileextensions = "*.qml *.qdoc *.cpp"
 headers.fileextensions = "*.h"
-outputdir = html
-outputformats = HTML
 version = 0.1
 syntaxhighlighting = true
 sourceencoding = UTF-8
 outputencoding = UTF-8
+outputdir                  = ditaxml
+outputformats              = DITAXML

modules/Material/Action.qml

@@ -20,7 +20,6 @@
 /*!
    \qmltype Action
    \inqmlmodule Material 0.1
-   \ingroup material
 
    \brief Represents an action shown in an action bar, context menu, or list.
 

modules/Material/ActionBar.qml

@@ -24,7 +24,6 @@ import Material.ListItems 0.1 as ListItem
 /*!
    \qmltype ActionBar
    \inqmlmodule Material 0.1
-   \ingroup material
 
    \brief An action bar holds the title and actions displayed in the application toolbar.
 

modules/Material/ActionButton.qml

@@ -24,7 +24,6 @@ import QtGraphicalEffects 1.0
 /*!
    \qmltype ActionBar
    \inqmlmodule Material 0.1
-   \ingroup material
 
    \brief A floating action button.
 

modules/Material/ApplicationWindow.qml

@@ -23,7 +23,6 @@ import Material 0.1
 /*!
    \qmltype ApplicationWindow
    \inqmlmodule Material 0.1
-   \ingroup material
 
    \brief A window that provides features commonly used for Material Design apps.
 

modules/Material/Page.qml

@@ -23,7 +23,6 @@ import Material 0.1
 /*!
    \qmltype ActionBar
    \inqmlmodule Material 0.1
-   \ingroup material
 
    \brief Brief description...
 

modules/Material/ProgressBar.qml

@@ -24,7 +24,6 @@ import Material 0.1
 /*!
    \qmltype ProgressBar
    \inqmlmodule Material
-   \ingroup material
 
    \brief Visual indicator of progress in some operation.
 */

modules/Material/ProgressCircle.qml

@@ -23,7 +23,6 @@ import Material 0.1
 /*!
    \qmltype ProgressCircle
    \inqmlmodule Material
-   \ingroup material
 
    \brief Visual circular indicator of progress in some operation.
 */

modules/Material/Sidebar.qml

@@ -20,27 +20,29 @@ import Material 0.1
 import "ListItems" as ListItem
 
 /*!
-    \qmltype Sidebar
-    \brief A sidebar component for use in adaptive layouts
+   \qmltype Sidebar
+   \inqmlmodule Material 0.1
 
-    To use, simply add an instance to your code, and anchor other components to it.
+   \brief A sidebar component for use in adaptive layouts
 
-    To show or hide, set the expanded property.
+   To use, simply add an instance to your code, and anchor other components to it.
 
-    By default, the sidebar has a flickable built in, and whatever contents are added
-    will be placed in the flickable. When you want this disabled, or want to fill the
-    entire sidebar, set the autoFill property to false.
+   To show or hide, set the expanded property.
 
-    Examples:
-    \qml
-        property bool wideAspect: width > units.gu(80)
+   By default, the sidebar has a flickable built in, and whatever contents are added
+   will be placed in the flickable. When you want this disabled, or want to fill the
+   entire sidebar, set the autoFill property to false.
 
-        Sidebar {
-            expanded: wideAspect
+   Examples:
+   \qml
+       property bool wideAspect: width > units.gu(80)
 
-            // Anchoring is automatic
-        }
-    \endqml
+       Sidebar {
+           expanded: wideAspect
+
+           // Anchoring is automatic
+       }
+   \endqml
 */
 View {
     id: root

modules/Material/Theme.qml

@@ -22,7 +22,6 @@ pragma Singleton
 /*!
    \qmltype Theme
    \inqmlmodule Material 0.1
-   \ingroup material
 
    \brief Provides access to standard colors that follow the Material Design specification.
 

modules/Material/ThemePalette.qml

@@ -20,7 +20,6 @@ import QtQuick 2.0
 /*!
    \qmltype Theme
    \inqmlmodule Material 0.1
-   \ingroup material
 
    \brief Provides access to standard colors that follow the Material Design specification, but
    specifically designed for light or dark surfaces.

modules/Material/Tooltip.qml

@@ -22,7 +22,6 @@ import Material.Extras 0.1
 /*!
    \qmltype Tooltip
    \inqmlmodule Material 0.1
-   \ingroup material
 
    \brief A tooltip is a label that appears on hover and explains a non-text UI element.
 

modules/Material/Window.qml

@@ -22,7 +22,6 @@ import QtQuick.Window 2.2
 /*!
    \qmltype Window
    \inqmlmodule Material 0.1
-   \ingroup material
 
    \brief A subclass of \l Window that provides some additional features for developing Applications
    that conform to Material Design.

modules/Material/units.qml

@@ -22,7 +22,6 @@ pragma Singleton
 /*!
    \qmltype units
    \inqmlmodule Material 0.1
-   \ingroup material
 
    \brief Provides access to screen-independent units known as DPs (device-independent pixels).