Cordova Docs

Introduction

This repository contains the source code for the Cordova website. This covers cordova.io (= cordova.apache.org) and its subdomains docs.cordova.io (= cordova.apache.org/docs) and plugins.cordova.io (= cordova.apache.org/plugins).

Table of Contents

• Introduction
• Table of Contents
• Installing
  • Ruby
    • Mac OS X
    • Windows
    • Linux
    • Verify Ruby
  • Python
    • Mac OS X
    • Windows
    • Linux
    • Verify Python
  • Node.js
    • Mac OS X & Windows
    • Linux
    • Verify Node.js
  • Dependencies
    • Ruby
    • JavaScript
  • Make (optional)
    • Windows
    • Mac OS X
    • Linux
    • Verify make
• Building
• Developing
  • Docs Redirects
• Deploying
• Working on the Documentation
• Adding a Tool or a Showcase App
• Writing a Blog Post
• Troubleshooting
  • Error: EMF, too many open files
  • Error: spawn ENOENT
  • Permission issues during Ruby install
  • Other Problems
• Attributions

Installing

Ruby

Ruby 2.0 is required to build the docs. NOTE: The docs will not build with Ruby 1.8, 1.9 or 2.4.

Mac OS X

Install Homebrew from this site, and then run:

brew install [email protected]

Windows

Follow these steps:

1. Download this installer from this page.
2. Run the downloaded file.
   1. Use the default installation path (usually C:\Ruby22).
   2. Make sure the 'add executable to path' option is checked.
3. Download this Ruby DevKit self-extracting archive from the same website.
4. Run the downloaded file.
   1. Use the following extraction path: C:\Ruby22DevKit.
5. Open cmd.exe.

   1. Go to the extraction path:

       cd C:\Ruby22DevKit
      

   2. Run these commands (following any instructions they give):

       ruby dk.rb init
       ruby dk.rb install
      

   3. Close cmd.exe.

Linux

Run the commands from this site that apply to your Linux distribution.

Verify Ruby

Verify your Ruby installation by running:

ruby --version

Python

Python 2.7 is also required to build the docs. NOTE: The docs will not build with Python 3.0 or greater.

Mac OS X

Mac OS X comes with Python 2.7 pre-installed. Else, follow these steps:

1. Download this installer from this page.
2. Run the downloaded file.

Windows

Follow these steps:

1. Download this installer from this page.
2. Run the downloaded file.
   1. Use the default installation path
   2. Make sure the 'add executable to path' option is checked.

Linux

The latest version of CentOS, Fedora, Redhat Enterprise (RHEL) and Ubuntu come with Python 2.7 pre-installed. Else, follow the steps from this site.

Verify Python

Verify your Python installation by running:

python --version

The version must be 2.7.x.

Node.js

Mac OS X & Windows

Go to this site, and click the "Install" button. Then run the downloaded file and follow the on-screen instructions. Make sure that the option to install NPM is enabled, if you see one.

Linux

Linux, follow the instructions on this site.

Verify Node.js

Verify your Node.js installation by running:

node --version
npm --version

Dependencies

Ruby

Once Ruby and Node.js are installed, install Ruby dependencies by running:

gem install bundler
bundle install --path ./ruby_modules

This will install the required Ruby Gems locally into a subfolder called ruby_modules in your repo folder. On some systems, the above commands need to be prefixed with sudo. Similarly on Windows, the cmd window in which those commands are to be run might need to have been "Run as Administrator."

JavaScript

Finally, install Node.js and JavaScript dependencies by running:

npm install

Make (optional)

The website can be built with Gulp or Make. The Gulp workflow is enabled by just installing all the JavaScript dependencies. The Make workflow usually allows for faster builds, but requires installation of the make tool.

Windows

Make can be installed on Windows from this page by downloading the setup tool and running it.

Mac OS X

Make comes with the Xcode Command Line Tools. To install them, run:

xcode-select --install

Linux

Make is installed by default on Linux.

Verify make

Verify your make installation by running:

make --version

Building

To build the whole website, run:

node_modules/.bin/gulp build --prod

The built website will be in a folder called build-prod.

Developing

To work on the website and see changes live as you save, run:

node_modules/.bin/gulp serve

That command will build the site and start a local server. To work on only the website without the docs, add the --nodocs flag, as follows:

node_modules/.bin/gulp serve --nodocs

Alternatively, to dynamically rebuild the site and refresh the browser when changes happen (again, optionally with the --nodocs flag), run:

node_modules/.bin/gulp watch

Docs Redirects

See doc/redirects.md.

Deploying

This section requires basic knowledge of SVN. If you do not know how to use SVN, refer to this tutorial.

To build the full website, run:

node_modules/.bin/gulp build --prod

A folder called build-prod will be created, and will contain the built website. Then, in a directory one level above the cordova-docs repository, check out the SVN repository that contains the currently deployed website by running the following command (committer access required):

cd ..
svn checkout https://svn.apache.org/repos/asf/cordova/site cordova-website

Then, move into the cordova-website repository and synchronise it with the SVN server:

cd cordova-website
svn update

Copy the cordova-docs/build-prod/ directory to the public directory in SVN like so:

cd ..
cp -R cordova-docs/build-prod/. cordova-website/public/

Some files will be new (? in SVN, and need to be svn added) and some files will be changed (M in SVN; no action required). To see just the ? changes, run:

cd cordova-website
svn status | grep "?"

Once you are satisfied that you have added the required changes, commit with a message:

svn commit -m "Updated docs"

NOTE: The commit might take a while (up to 1 hour), depending on the number of files changed.

Working on the Documentation

Refer to doc/README/en/README.md for information about writing documentation.

Note: many changes to the overall documentation come from other repos and are simply pulled together by a build. tools/bin/fetch_docs.js has more details and www/_data/fetched-files.yml contains an informative list of src/dest pairs. Most auto-generated files have a comment tag at the top of the file to indicate that they come from elsewhere.

Adding a Tool or a Showcase App

See doc/tool-or-showcase.md.

Writing a Blog Post

See doc/blogpost.md.

Troubleshooting

Error: EMF, too many open files

Increase the maximum number of open files on the system:

ulimit -n 10480

Error: spawn ENOENT

Run:

gulp clean

Permission issues during Ruby install

You could try a different method to install Ruby. Checkout rbenv. Instructions:

1. Install rbenv

    brew install rbenv ruby-build
   

2. Add eval "$(rbenv init -)" to the end of your .bash_profile:

    echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
   

3. Install a version of ruby and set it to your local version:

    rbenv install 2.0.0-p647
    rbenv local 2.0.0-p647
   

Other Problems

Please ask for help on the Slack channel. Join at slack.cordova.io.

Attributions

For attributions for used open-source work, please see the attributions page: www/attributions.html.