Apache Cordova API Documentation
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/ docs/LANGUAGE/versions.js docs/commondata.js
That's file structure of docs how they appears on the server.
When generated these content could be found in the
public folder, inside the project.
versions.js is file which contains array of all doc versions for specific language. That file would be loaded by website JS
and allow older docs to be aware more recent version of docs. That's limit need to publish whole docs as single piece.
commondata.js is file which contains array of all languages supported by documentation now, also . That file would be loaded by website JS
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.
Source files structure
docs/ docs/LANGUAGE docs/LANGUAGE/VERSION docs/LANGUAGE/VERSION/cordova/ docs/LANGUAGE/VERSION/guide/platforms/PLATFORMNAME/ template/docs/default template/docs/LANGUAGE
Docs consists from two parts - Source files for each language and HTML/CSS/JS templates for the docs. The docs for all languages except English translated using Crowdin. Please don't edit these in this repository, these changes would be overridden by export from Crowdin.
Templates are set of HTML/CSS/JS files. By default used template within
template/docs/default. When generating docs for any language
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
without need to duplicate all assets in each template.
Contributing to the Documentation
Report or Fix an Issue
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.
Sending Pull Requests
Pull requests are welcome!
We appreciate the use of topic branches.
git checkout -b CB-9923 # code git commit -m "CB-9923: Fix a bad bug." git push origin CB-9923 # send pull request from branch CB-9923 to cordova:master
Please don't send pull requests for the languages other then English, use Crowdin
Adding a Language
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. Merge files a still implemented, but not used.
2. Customizing HTML template
Each language can override the default template in
You don't need copy content of whole
template/docs/default inside language specific template,
you just override only these files which you need modify. Other files would be picked up from
Please see the
STYLESHEET.md file for guidelines on language and usage.
Generating Documentation with Node.js
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
Setting up Node.js
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.
Generating a Version Release
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
QA for docs & translation
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 mess up 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.
Translation Report tool.
translationreport currently provide two QA checks for translation.
- It verifies that autolinking works after translation, and that translated text point to the same pages as in the original documentation.
- It verifies that translated and original files create same DOM structure, since after exporting from Crowdin, the markdown files could contain unnecessary lines, which lead to broken HTML, and could create not needed code sections for example.
Validate JSDoc tool.
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.
Recommendations for the translators
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 configuration 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 than 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.
mkdir -p tmp/ru 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 (assuming PowerShell):
cp -r -force tmp/ru/cordova-docs/docs/ru/edge docs/ru/
Remove temporary directory. In my case
rm -f tmp/ru
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 translate.
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
-vwhich 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 errors reappear after next export from Crowdin, so don't hunt for these errors until release, or create tool which will fix these errors after each export and use it.
Now you ready to create pull request with documentation to the main