a1e9eb222775ea879e6bcdf5a1fe6e8a9f226a65
[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/guide/platforms/PLATFORMNAME/
21
22 Contributing to the Documentation
23 ---------------------------------
24
25 ### Report or Fix an Issue
26
27 We use [Apache JIRA](https://issues.apache.org/jira/browse/CB)
28
29 By the way, you rock! Thanks for helping us improve the documentation!
30
31 ### Using Git
32
33 Are you new to Git or contributing on GitHub?
34
35 We have [written a few Git tutorials](http://wiki.apache.org/cordova/ContributorWorkflow)
36 to help you get started with contributing to the documentation.
37
38 ### Sending Pull Requests
39
40 Pull requests are welcome!
41
42 We appreciate the use of topic branches.
43
44     git checkout -b issue_23
45
46     # code
47
48     git commit -m "Issue 23: Fix a bad bug."
49
50     git push origin issue_23
51
52     # send pull request from branch issue_23 to cordova:master
53
54 ### Adding a Language
55
56 Do you want the Apache Cordova documentation in another language? We do too!
57 With the support of [Crowdin](http://crowdin.net/project/cordova),
58 a translation and localization management platform, translators can login to
59 the easy-to-use tooling and provide as much or as little translation assistance as
60 they would like. If you know another language please support Cordova and contribute.
61 http://crowdin.net/project/cordova. For some best practices for using the
62 Crowdin tool please see our wiki http://wiki.apache.org/cordova/CordovaTranslations.
63
64 Cordova language administrators, don't forget these steps:
65
66 __1. config.json__
67
68 For each language and version, there is a `config.json` that defines the name of the language and
69 how to merge the files.
70
71 __2. Customizing HTML template__
72
73 Each language can override the default template in `template/docs/LANGUAGE`.
74
75 ### Editorial Guidelines
76
77 Please see the `STYLESHEET.md` file for guidelines on language and usage.
78
79 ## Generating Documentation with Node.js
80
81 Right now documentation could be run using Node.js either on Windows, or on Linux box.
82
83     $ rm -r tmp public      # Clear out old docs
84     $ ./bin/genjs           # compile all docs
85     $ ./bin/genjs en edge   # compile English Edge docs
86     $ ./bin/genjs ru edge   # compile Russian Edge docs
87     $ ./bin/genjs es 3.5.0  # compile Spanish 3.5.0 docs
88     
89 ### Setting up Node.js
90
91 1. Go to Node.JS [downloads page](http://nodejs.org/download/)
92 2. Download and install package for your operation system.
93 3. Checkout this repository using Git
94
95         git clone https://github.com/apache/cordova-docs
96
97 4. Install dependencies. In the root of the cloned cordova-docs folder run
98    
99         npm install
100 5. Now you able to build documentation locally.
101
102 ### Quick Preview
103
104 When making minor edits, it is usually safe to simply render the edited from
105 Markdown to HTML. Many code editors have plugins to render Markdown to HTML
106 and there are a handful of [good](http://dillinger.io/) online editors.
107
108 Currently, a Node.JS script and [joDoc-js](https://github.com/kant2002/jodoc-js) are
109 used to generate the HTML documentation.
110
111 Generating a Version Release
112 ---------------------------
113
114 There is a Rake task to increment the version, generate the version directory, and update the edge documentation.
115
116     # generate version 4.1.0 for english.
117     .\bin\incrementversion en 4.1.0
118
119 QA for docs & translation
120 ---------------------------
121 In order to maintain quality of documentation and translation, following tools could be used.
122
123 1. `fixyaml` tool.
124 2. `translationreport` tool.
125 3. `validatejsdoc` tool.
126
127 ### FixYaml tool.
128 The tool `fixyaml` created to automatically fix YAML headers in the translation files after
129 exporting translated content from CrowdIn. Sometimes Crowdin messup with Apache license headers 
130 and this tool created to fix that.
131
132 Usage:
133
134     bin\fixyaml             # Runs fixyaml across all docs.
135     bin\fixyaml ru          # Runs fixyaml across all Russian docs.
136     bin\fixyaml ru edge     # Runs fixyaml on the latest Russian docs.
137     bin\fixyaml ru 5.0.0    # Runs fixyaml on the version 5.0.0 of Russian docs.
138
139 ### Translation Report tool.
140 The tool `translationreport` currently provide two QA checks for translation.
141 1. It verifies that autolinking works after translation, and that translated text point to the same pages as 
142 in the original documentation.
143 2. It verifies that translated and original files create same DOM structure, since after exporting from 
144 Crowdin, the markdown files could contain unnescessary lines, which lead to broken HTML, and could create 
145 not needed code sections for example.
146
147 ### Validate JSDoc tool.
148 The tool `validatejsdoc` allow verification of the current implementation of JSDoc with reference implementation.
149 It was used during porting JSDoc to the Node version of JSDoc, and now currently not used in the workflow.
150
151 Recommendations for the translators
152 -------------------------
153 If you intend to create quality translation of the Cordova docs, please not only 
154 work in Crowdin and translate documentation, but also please go extra mile and verify that
155 generated documentation for your language is also produce quality results.
156
157 For that you should have Crowdin CLI tool. You could
158 1. take it from [here](https://crowdin.com/page/cli-tool) 
159 2. or install alternate NodeJS client
160     
161     `npm -g install crowdin-cli`
162
163 You will use that tool for the downloading translation from Crowdin. 
164 To be able to download translated content from the Crowdin you should have API key for the project.
165 Please ask for it on the mailing list.
166
167 After you receive access to API key, create `crowdin.yaml` coniguration file, as described in the [CrowdIn cli tool page](https://crowdin.com/page/cli-tool).
168
169 Now you ready to download content from CrowdIn.
170 Run following commands (All commands here would be for NodeJS version of Crowdin CLI)
171
172 1. Prepare translated content for downloading.
173
174    `crowdin-cli export`
175    
176    This command collect latest translations and made them available for downloading. Without that command, the translation which you would download would be stalled.
177    Be careful with this command, since Crowdin implement throttling and allow you export content not faster then 1 time in 30 minutes, or so.
178 2. Download content for you language. I will use Russian as example.
179
180    `crowdin-cli download -l ru -o ru.zip`
181    
182    This command download all translations for Russian language to the `ru.zip` file.
183    
184 3. Now unpack the download content to the temporary directory.
185
186    `unzip -x ru.zip -d tmp/ru`
187    
188 4. Copy the unpacked content to the `docs` folder.
189
190    a) on Linux: 
191     `cp tmp/ru/cordova-docs/docs/ru/edge/* docs/ru/edge/`
192  
193    b) on Windows:
194     `xcopy tmp/ru/cordova-docs/docs/ru/edge/* docs/ru/edge/`
195     
196 5. Remove temporary directory. In my case `tmp/ru`.
197
198    Now you have fresh translation and could generate content.
199    
200 6. Fix Yaml headers by running.
201
202    `bin/fixyaml ru edge`
203
204 7. Run generator. You should generate both English version and language which you tranlate.
205
206    ```
207    bin/genjs en edge
208    bin/genjs ru edge
209    ```
210    
211    The generated documentation contains in the `public/en/edge` and `public/ru/edge`
212    
213    You need both versions, to validate that translated docs would have same structure as original documentation.
214    
215 8. Validate you translation.
216
217    `bin/translationreport ru edge`
218    
219    This will give you list of files which has structural differences from the original docs.
220    Below the example output:
221    ```
222     => Validating translation for version edge on language ru...
223    Comparing C:\Users\kant\Documents\GitHub\cordova-docs\public\en\edge
224    with C:\Users\kant\Documents\GitHub\cordova-docs\public\ru\edge
225    Path guide_platforms_blackberry10_upgrade.md.html is different.
226    Path guide_platforms_blackberry_upgrade.md.html is different.
227    Path guide_platforms_ios_tools.md.html is different.
228    Path guide_support_index.md.html is different.
229    ```
230
231 9. Now you could open pregenerated files and compare the English version with your translated versions.
232     Open both versions and find out what's wrong.
233     
234     If on the first sight you could not find the differences, you could add switch `-v` which will increase verbosity of the tool.
235     For example: 
236     
237     `bin/translationreport ru edge -v`
238     
239 10. Currently there two type of errors reported: 
240
241     a. Missing or additional links.
242     
243     b. The broken HTML structure.
244     
245 11. Let's fix first type of errors - Missing/Additional links.
246     To fix these type of errors you have to make sure that text in your translation where you want to have link,
247     match exactly the header in the translated document, otherwise auto-linking would not work.
248     You have to rephrase the sentences to fix that.
249     
250 12. Broken HTML DOM structure.
251
252     Most likely this type of errors caused by the additional lines created by Crowdin during export.
253     You have to manually spot these places and remove additional lines when needed and then commit your changes to Git.
254     Most likely these erorrs reappear after next exprot from CrowdIn, so don't hunt for these errors until release, or create 
255     tool which will fix these error after each export and use it.
256     
257 13. Now you ready to create pull request with documentation to the main `crodova-docs` repository. 
258
259 Enjoy translation!!!