|author||Steve Gill <firstname.lastname@example.org>||Mon Jun 15 16:53:52 2015 -0700|
|committer||Steve Gill <email@example.com>||Mon Jun 15 16:53:52 2015 -0700|
The documentation is available at docs.cordova.io.
All of the Apache Cordova documentation is written with markdown, 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.
docs/ docs/LANGUAGE docs/LANGUAGE/VERSION docs/LANGUAGE/VERSION/cordova/ docs/LANGUAGE/VERSION/guide/platforms/PLATFORMNAME/
We use Apache JIRA
By the way, you rock! Thanks for helping us improve the documentation!
Are you new to Git or contributing on GitHub?
We have written a few Git tutorials to help you get started with contributing to the documentation.
Pull requests are welcome!
We appreciate the use of topic branches.
git checkout -b issue_23 # code git commit -m "Issue 23: Fix a bad bug." git push origin issue_23 # send pull request from branch issue_23 to cordova:master
Do you want the Apache Cordova documentation in another language? We do too! With the support of Crowdin, a translation and localization management platform, translators can login to the easy-to-use tooling and provide as much or as little translation assistance as they would like. If you know another language please support Cordova and contribute. http://crowdin.net/project/cordova. For some best practices for using the Crowdin tool please see our wiki http://wiki.apache.org/cordova/CordovaTranslations.
Cordova language administrators, don't forget these steps:
For each language and version, there is a
config.json that defines the name of the language and how to merge the files.
2. Customizing HTML template
Each language can override the default template in
Please see the
STYLESHEET.md file for guidelines on language and usage.
Right now documentation could be run using Node.js either on Windows, or on Linux box.
$ rm -r tmp public # Clear out old docs $ ./bin/genjs # compile all docs $ ./bin/genjs en edge # compile English Edge docs $ ./bin/genjs ru edge # compile Russian Edge docs $ ./bin/genjs es 3.5.0 # compile Spanish 3.5.0 docs
Go to Node.JS downloads page
Download and install package for your operation system.
Checkout this repository using Git
git clone https://github.com/apache/cordova-docs
Install dependencies. In the root of the cloned cordova-docs folder run
Now you able to build documentation locally.
When making minor edits, it is usually safe to simply render the edited from Markdown to HTML. Many code editors have plugins to render Markdown to HTML and there are a handful of good online editors.
Currently, a Node.JS script and joDoc-js are used to generate the HTML documentation.
There is a Rake task to increment the version, generate the version directory, and update the edge documentation.
# generate version 4.1.0 for english. .\bin\incrementversion en 4.1.0
In order to maintain quality of documentation and translation, following tools could be used.
fixyaml created to automatically fix YAML headers in the translation files after exporting translated content from CrowdIn. Sometimes Crowdin messup with Apache license headers and this tool created to fix that.
bin\fixyaml # Runs fixyaml across all docs. bin\fixyaml ru # Runs fixyaml across all Russian docs. bin\fixyaml ru edge # Runs fixyaml on the latest Russian docs. bin\fixyaml ru 5.0.0 # Runs fixyaml on the version 5.0.0 of Russian docs.
translationreport currently provide two QA checks for translation.
validatejsdoc allow verification of the current implementation of JSDoc with reference implementation. It was used during porting JSDoc to the Node version of JSDoc, and now currently not used in the workflow.
If you intend to create quality translation of the Cordova docs, please not only work in Crowdin and translate documentation, but also please go extra mile and verify that generated documentation for your language is also produce quality results.
For that you should have Crowdin CLI tool. You could
take it from here
or install alternate NodeJS client
npm -g install crowdin-cli
You will use that tool for the downloading translation from Crowdin. To be able to download translated content from the Crowdin you should have API key for the project. Please ask for it on the mailing list.
After you receive access to API key, create
crowdin.yaml coniguration file, as described in the CrowdIn cli tool page.
Now you ready to download content from CrowdIn. Run following commands (All commands here would be for NodeJS version of Crowdin CLI)
Prepare translated content for downloading.
This command collect latest translations and made them available for downloading. Without that command, the translation which you would download would be stalled. Be careful with this command, since Crowdin implement throttling and allow you export content not faster then 1 time in 30 minutes, or so.
Download content for you language. I will use Russian as example.
crowdin-cli download -l ru -o ru.zip
This command download all translations for Russian language to the
Now unpack the download content to the temporary directory.
unzip -x ru.zip -d tmp/ru
Copy the unpacked content to the
a) on Linux:
cp tmp/ru/cordova-docs/docs/ru/edge/* docs/ru/edge/
b) on Windows:
xcopy tmp/ru/cordova-docs/docs/ru/edge/* docs/ru/edge/
Remove temporary directory. In my case
Now you have fresh translation and could generate content.
Fix Yaml headers by running.
bin/fixyaml ru edge
Run generator. You should generate both English version and language which you tranlate.
bin/genjs en edge bin/genjs ru edge
The generated documentation contains in the
You need both versions, to validate that translated docs would have same structure as original documentation.
Validate you translation.
bin/translationreport ru edge
This will give you list of files which has structural differences from the original docs. Below the example output:
=> Validating translation for version edge on language ru... Comparing C:\Users\kant\Documents\GitHub\cordova-docs\public\en\edge with C:\Users\kant\Documents\GitHub\cordova-docs\public\ru\edge Path guide_platforms_blackberry10_upgrade.md.html is different. Path guide_platforms_blackberry_upgrade.md.html is different. Path guide_platforms_ios_tools.md.html is different. Path guide_support_index.md.html is different.
Now you could open pregenerated files and compare the English version with your translated versions. Open both versions and find out what's wrong.
If on the first sight you could not find the differences, you could add switch
-v which will increase verbosity of the tool. For example:
bin/translationreport ru edge -v
Currently there two type of errors reported:
a. Missing or additional links.
b. The broken HTML structure.
Let's fix first type of errors - Missing/Additional links. To fix these type of errors you have to make sure that text in your translation where you want to have link, match exactly the header in the translated document, otherwise auto-linking would not work. You have to rephrase the sentences to fix that.
Broken HTML DOM structure.
Most likely this type of errors caused by the additional lines created by Crowdin during export. You have to manually spot these places and remove additional lines when needed and then commit your changes to Git. Most likely these erorrs reappear after next exprot from CrowdIn, so don't hunt for these errors until release, or create tool which will fix these error after each export and use it.
Now you ready to create pull request with documentation to the main