Apache Cordova API Documentation
The JavaScript API documentation for Apache Cordova.
The documentation is available at docs.cordova.io.
Documentation Format
All of the Apache Cordova documentation is written with markdown, a lightweight markup language that can be typeset to HTML. Markdown provides a simple and flexible way to document Cordova's core API and platform-specific APIs.
File Structure
docs/
docs/LANGUAGE
docs/LANGUAGE/VERSION
docs/LANGUAGE/VERSION/cordova/
docs/LANGUAGE/VERSION/cordova/PluginName/
docs/LANGUAGE/VERSION/cordova/PluginName/className.md
docs/LANGUAGE/VERSION/cordova/PluginName/className.functionName.md
Contributing to the Documentation
Report or Fix an Issue
We use Apache JIRA
By the way, you rock! Thanks for helping us improve the documentation!
Using Git
Are you new to Git or contributing on GitHub?
We have written a few Git tutorials to help you get started with contributing to the documentation.
Sending Pull Requests
Pull requests are welcome!
We appreciate the use of topic branches.
git checkout -b issue_23
# code
git commit -m "Issue 23: Fix a bad bug."
git push origin issue_23
# send pull request from branch issue_23 to cordova:master
Adding a Language
Do you want the Apache Cordova documentation in another language? We do too! With the support of Crowdin, a translation and localization management platform, translators can login to the easy-to-use tooling and provide as much or as little translation assistance as they would like. If you know another language please support Cordova and contribute. http://crowdin.net/project/cordova. For some best practices for using the Crowdin tool please see our wiki http://wiki.apache.org/cordova/CordovaTranslations.
Cordova language administrators, don't forget these steps:
1. config.json
For each language and version, there is a config.json
that defines the name of the language and
how to merge the files.
2. Customizing HTML template
Each language can override the default template in template/docs/LANGUAGE
.
Editorial Guidelines
Please see the STYLESHEET.md
file for guidelines on language and usage.
Generating Documentation with Vagrant
It can be trouble generating the documentation. Juggling Ruby environments and the dependencies can be a sensitive matter.
To make our lives easier, Vagrant support has been added to our documentation generator. It's easy to setup and works on all the major operating systems. After you've installed Vagrant and VirtualBox, you only need to run one command to download and provision a light-weight virtual machine (approx 200MB). At that point all the dependencies exist inside the virtual machine, so you don't need to install them manually on your bare metal machine.
Setup
Initialize Vagrant Box
$ cd cordova-docs/
$ vagrant up
Build the Documentation
$ vagrant ssh
$ cd /vagrant # shared copy of this repo
$
$ ./bin/generate # compile all docs
$ ./bin/generate en edge # compile English Edge docs
$
$ exit # exit the ssh tunnel
The /vagrant
directory is a shared copy of this repository. When the
documentation is done generating, you will see a public/
directory on
both your virtual and local machine.
Shutdown the Virtual Machine
Pick one of the following, depending on what you want to do:
$ vagrant suspend # pause the vm and save its state
$ vagrant halt # shutdown the vm
$ vagrant destroy # delete the vm and all its contents
Generating Documentation Locally
Install
-
Clone joDoc
git clone http://github.com/davebalmer/joDoc.git
-
Install markdown
curl -O http://daringfireball.net/projects/downloads/Markdown_1.0.1.zip unzip Markdown_1.0.1.zip chmod u+x Markdown_1.0.1/Markdown.pl mv Markdown_1.0.1/Markdown.pl markdown rm -r Markdown_1*
-
Install Ruby Dependencies
curl -sSL https://get.rvm.io | bash -s stable rvm install 1.8.7 gem install bundler bundle install
Run the Script
Generate all versions
PATH=$PATH:$PWD/joDoc:$PWD bin/generate
Generate a specific language and version
PATH=$PATH:$PWD/joDoc:$PWD bin/generate en edge
or as a shortcut
PATH=$PATH:$PWD/joDoc:$PWD bin/generate --edge
Quick Preview
When making minor edits, it is usually safe to simply render the edited from Markdown to HTML. Many code editors have plugins to render Markdown to HTML and there are a handful of good online editors.
Currently, a Ruby script and joDoc are used to generate the HTML documentation.
Generating a Version Release
There is a Rake task to increment the version, generate the version directory, and update the edge documentation.
# generate version 1.7.0 for english.
rake version[1.7.0,en]
If while running rake you get the error
no such file to load -- spec/rake/spectask
then run
gem install rspec -v 1.3.0
FAQ
./bin/generate
Error while running If you get the following error:
./bin/../lib/cordova/navigation_menu.rb:14:in `read': can't convert nil into String (TypeError)
from ./bin/../lib/cordova/navigation_menu.rb:14:in `initialize'
from ./bin/../lib/docs_generator.rb:86:in `new'
from ./bin/../lib/docs_generator.rb:86:in `after_jodoc'
from ./bin/../lib/docs_generator.rb:55:in `run'
from ./bin/../lib/docs_generator.rb:45:in `foreach'
from ./bin/../lib/docs_generator.rb:45:in `run'
from ./bin/../lib/docs_generator.rb:41:in `foreach'
from ./bin/../lib/docs_generator.rb:41:in `run'
from ./bin/generate:6
You may need to add the following line to the joDoc script:
$markdown_bin = "/path/to/Markdown.pl";
For more details, see the Issue #590.
Error with ruby and nokogiri versions
If you get the following error:
custom_require.rb:36:in `require': /lib/cordova/jodoc.rb:28: syntax error, unexpected tCONSTANT, expecting ']' (SyntaxError)
@template_directories = [ File.join TEMPLATE_PATH, 'default' ]
^
-
You may need to downgrade the version of ruby to 1.8.7 and nokogiri to 1.5.2 Use rvm and the Gemfile provided to install the dependencies
rvm install 1.8.7 rvm use 1.8.7 bundle install