984228b432f0093d1dcf08ef38b71b6ebe2a72e7
[cordova-docs.git] / README.md
1 Apache Cordova API Documentation
2 ================================
3
4 The JavaScript API documentation for [Apache Cordova](http://cordova.io/).
5
6 The documentation is available at [docs.cordova.io](http://docs.cordova.io/).
7
8 Documentation Format
9 --------------------
10
11 All of the [Apache Cordova](http://cordova.io/) documentation is written with [markdown](http://daringfireball.net/projects/markdown/syntax), 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.
12
13 File Structure
14 --------------
15
16     docs/
17     docs/LANGUAGE
18     docs/LANGUAGE/VERSION
19     docs/LANGUAGE/VERSION/cordova/
20     docs/LANGUAGE/VERSION/cordova/PluginName/
21     docs/LANGUAGE/VERSION/cordova/PluginName/className.md
22     docs/LANGUAGE/VERSION/cordova/PluginName/className.functionName.md
23
24 Contributing to the Documentation
25 ---------------------------------
26
27 ### Report or Fix an Issue
28
29 We use [Apache JIRA](https://issues.apache.org/jira/browse/CB)
30
31 By the way, you rock! Thanks for helping us improve the documentation!
32
33 ### Using Git
34
35 Are you new to Git or contributing on GitHub?
36
37 We have [written a few Git tutorials](http://wiki.apache.org/cordova/ContributorWorkflow)
38 to help you get started with contributing to the documentation.
39
40 ### Sending Pull Requests
41
42 Pull requests are welcome!
43
44 We appreciate the use of topic branches.
45
46     git checkout -b issue_23
47
48     # code
49
50     git commit -m "Issue 23: Fix a bad bug."
51
52     git push origin issue_23
53
54     # send pull request from branch issue_23 to cordova:master
55
56 ### Adding a Language
57
58 Do you want the Apache Cordova documentation in another language? We do too!
59 With the support of <a href="http://crowdin.net/project/cordova">Crowdin</a>,
60 a translation and localization management platform, translators can login to
61 the easy-to-use tooling and provide as much or as little translation assistance as
62 they would like. If you know another language please support Cordova and contribute.
63 <a href="http://crowdin.net/project/cordova">http://crowdin.net/project/cordova</a>.
64
65 ordova language administrators, don't forget these steps: 
66
67 __1. config.json__
68
69 For each language and version, there is a `config.json` that defines the name of the language and
70 how to merge the files.
71
72 __2. Customizing HTML template__
73
74 Each language can override the default template in `template/docs/LANGUAGE`.
75
76 ### Editorial Guidelines
77
78 Please see the `STYLESHEET.md` file for guildelines on language and usage.
79
80 Generating the Documentation
81 ----------------------------
82
83 ### Install
84
85 - Clone [joDoc](http://github.com/davebalmer/jodoc)
86
87         git clone http://github.com/davebalmer/joDoc.git
88
89 - Install markdown
90
91     curl -O http://daringfireball.net/projects/downloads/Markdown_1.0.1.zip
92     unzip Markdown_1.0.1.zip
93     chmod u+x Markdown_1.0.1/Markdown.pl
94     mv Markdown_1.0.1/Markdown.pl markdown
95     rm -r Markdown_1*
96
97 - Install Ruby Dependencies
98
99     curl -sSL https://get.rvm.io | bash -s stable
100     rvm install 1.8.7
101     gem install bundler
102     bundle install
103
104 ### Run the Script
105
106 Generate all versions
107
108     PATH=$PATH:$PWD/joDoc:$PWD bin/generate
109
110 Generate a specific language and version
111
112     PATH=$PATH:$PWD/joDoc:$PWD bin/generate en edge
113
114 or as a shortcut
115
116     PATH=$PATH:$PWD/joDoc:$PWD bin/generate --edge
117
118 ### Quick Preview
119
120 When making minor edits, it is usually safe to simply render the edited from
121 Markdown to HTML. Many code editors have plugins to render Markdown to HTML
122 and there are a handful of [good](http://dillinger.io/) online editors.
123
124 Currently, a Ruby script and [joDoc](http://github.com/davebalmer/jodoc) are
125 used to generate the HTML documentation.
126
127 Generating a Version Release
128 ---------------------------
129
130 There is a Rake task to increment the version, generate the version directory, and update the edge documentation.
131
132     # generate version 1.7.0 for english.
133     rake version[1.7.0,en]
134
135 If while running rake you get the error 
136
137     no such file to load -- spec/rake/spectask 
138
139 then run
140
141     gem install rspec -v 1.3.0
142
143 FAQ
144 ---
145
146 ### Error while running `./bin/generate`
147
148 If you get the following error:
149
150     ./bin/../lib/cordova/navigation_menu.rb:14:in `read': can't convert nil into String (TypeError)
151         from ./bin/../lib/cordova/navigation_menu.rb:14:in `initialize'
152         from ./bin/../lib/docs_generator.rb:86:in `new'
153         from ./bin/../lib/docs_generator.rb:86:in `after_jodoc'
154         from ./bin/../lib/docs_generator.rb:55:in `run'
155         from ./bin/../lib/docs_generator.rb:45:in `foreach'
156         from ./bin/../lib/docs_generator.rb:45:in `run'
157         from ./bin/../lib/docs_generator.rb:41:in `foreach'
158         from ./bin/../lib/docs_generator.rb:41:in `run'
159         from ./bin/generate:6
160
161 You may need to add the following line to the joDoc script:
162
163     $markdown_bin = "/path/to/Markdown.pl";
164
165 For more details, see the [Issue #590](https://issues.apache.org/jira/browse/CB-590).
166
167 ### Error with ruby and nokogiri versions
168
169 If you get the following error:
170
171     custom_require.rb:36:in `require': /lib/cordova/jodoc.rb:28: syntax error, unexpected tCONSTANT, expecting ']' (SyntaxError)
172     @template_directories = [ File.join TEMPLATE_PATH, 'default' ]
173                                                      ^
174 - You may need to downgrade the version of ruby to 1.8.7 and nokogiri to 1.5.2
175   Use rvm and the Gemfile provided to install the dependencies
176
177     rvm install 1.8.7
178     rvm use 1.8.7
179     bundle install
180