Skip to content

Latest commit

 

History

History
299 lines (202 loc) · 11.7 KB

README.md

File metadata and controls

299 lines (202 loc) · 11.7 KB

Apache Cordova API Documentation

The JavaScript API documentation for Apache Cordova.

The documentation is available at docs.cordova.io.

Documentation Format

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.

File Structure

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!

Using Git

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:

1. config.json

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 template/docs/LANGUAGE. 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 template/docs/default.

Editorial Guidelines

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

  1. Go to Node.JS downloads page

  2. Download and install package for your operation system.

  3. Checkout this repository using Git

     git clone https://github.com/apache/cordova-docs

  4. Install dependencies. In the root of the cloned cordova-docs folder run

     npm install

  5. Now you able to build documentation locally.

Quick Preview

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.

  1. fixyaml tool.
  2. translationreport tool.
  3. validatejsdoc tool.

FixYaml tool.

The tool 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.

Usage:

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.

The tool translationreport currently provide two QA checks for translation.

  1. It verifies that autolinking works after translation, and that translated text point to the same pages as in the original documentation.
  2. 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.

The 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

  1. take it from here

  2. 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)

  1. Prepare translated content for downloading.

    crowdin-cli export

    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.

  2. 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 ru.zip file.

  3. Now unpack the download content to the temporary directory.

    mkdir -p tmp/ru
unzip -x ru.zip -d tmp/ru

  4. Copy the unpacked content to the docs folder.

    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/

  5. Remove temporary directory. In my case tmp/ru.

    rm -f tmp/ru

    Now you have fresh translation and could generate content.

  6. Fix Yaml headers by running.

    bin/fixyaml ru edge

  7. 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 public/en/edge and public/ru/edge

    You need both versions, to validate that translated docs would have same structure as original documentation.

  8. 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.

  9. 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

  10. Currently there two type of errors reported:

    a. Missing or additional links.

    b. The broken HTML structure.

  11. 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.

  12. 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.

  13. Now you ready to create pull request with documentation to the main cordova-docs repository.

Enjoy translation!!!