e12e7e325dbdd59dd216468ea2461a3de7fcfcec
[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