CB-2606 Moved back BB10, Tizen; sort alpabetically
[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/ContributerWorkflow)
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
60 __1. Create the language directory__
61
62     # Spanish
63     mkdir docs/es
64
65 __2. Add a version__
66
67 Start with the latest stable release. You can always add other versions later.
68
69     mkdir docs/es/1.0.0
70
71 __3. Begin Translating__
72
73 Currently, English is the most up-to-date and so it is easiest to copy each English
74 file into the new language directory.
75
76 __4. config.json__
77
78 For each version, there is a `config.json` that defines the name of the language and
79 how to merge the files.
80
81 __5. Customizing HTML template__
82
83 Each language can override the default template in `template/docs/LANGUAGE`.
84
85 Generating the Documentation
86 ----------------------------
87
88 ### Quick Preview
89
90 When making minor edits, it is usually safe to simply render the edited from
91 Markdown to HTML. Many code editors have plugins to render Markdown to HTML
92 and there are a handful of [good](http://dillinger.io/) online editors.
93
94 Currently, a Ruby script and [joDoc](http://github.com/davebalmer/jodoc) are used to generate the HTML documentation.
95
96 ### Install joDoc
97
98 - Clone [joDoc](http://github.com/davebalmer/jodoc)
99
100         git clone http://github.com/davebalmer/joDoc.git
101         
102 - Add joDoc/ to your path
103     
104   Open `~/.bashrc` or `~/.profile` (or whatever you use)
105
106         export PATH=$PATH:~/path/to/joDoc/
107     
108 - Install markdown
109
110         # Use your package manager
111         brew install markdown
112
113 - Install nokogiri (Ruby HTML parser)
114
115         gem install nokogiri
116
117 - Install json (Ruby JSON parser)
118
119         gem install json
120
121 ### Run the Script
122
123     ./bin/generate
124
125 ### Problems
126     
127 Generated 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
133     rake version[1.7.0]
134
135 FAQ
136 ---
137
138 ### Error while running `./bin/generate`
139
140 If you get the following error:
141
142     ./bin/../lib/cordova/navigation_menu.rb:14:in `read': can't convert nil into String (TypeError)
143         from ./bin/../lib/cordova/navigation_menu.rb:14:in `initialize'
144         from ./bin/../lib/docs_generator.rb:86:in `new'
145         from ./bin/../lib/docs_generator.rb:86:in `after_jodoc'
146         from ./bin/../lib/docs_generator.rb:55:in `run'
147         from ./bin/../lib/docs_generator.rb:45:in `foreach'
148         from ./bin/../lib/docs_generator.rb:45:in `run'
149         from ./bin/../lib/docs_generator.rb:41:in `foreach'
150         from ./bin/../lib/docs_generator.rb:41:in `run'
151         from ./bin/generate:6
152
153 You may need to add the following line to the joDoc script:
154
155     $markdown_bin = "/path/to/Markdown.pl";
156
157 For more details, see the [Issue #590](https://issues.apache.org/jira/browse/CB-590).
158