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