Contributing APIDocs
Contents
Overview
This guide describes how to submit changes to Titanium's API documentation (APIDocs).
Finding the License
The Appcelerator Titanium SDK and its associated documentation are open source and licensed under the Apache Public License (version 2).
Signing the Contributors License Agreement (CLA)
Since Appcelerator itself is both an open source project and also a Company that is in charge of its long-term development, we require that you sign a standard Open Source Contributors License Agreement (CLA). As with most open source projects, legal issues regarding intellectual property rights require us to protect ourselves, our contributors and our users from any future ownership claims from third-parties.
Thus, you must first electronically sign the CLA before you can contribute code, documentation or any other materials to the project.
Getting the APIDocs Source Code
In the titanium_mobile repository on Github, within a directory called apidoc, resides the source code of the API Reference Guides section of our website.
Read the Style Guide
API doc contributions should comply with the Titanium Mobile API Doc Style Guide.
APIDoc Build Prerequisites
Python and some of its libraries must be installed before Titanium's APIDocs may be built. Refer to the Installing Python and Installing Python setuptools guides.
Generating the HTML APIDocs
The HTML used for the APIDocs website can be generated by changing to apidoc directory at the system shell and running the docgen.py script, as follows:
cd /path/to/titanium_mobile/apidoc
python ./docgen.pyThe HTML files are then output to the /path/to/titanium_mobile/dist/apidoc directory, with the index page at dist/apidoc/index.html.
Validating APIDoc Modifications
After changes have been made to the APIDoc source, it's important to verify that the code is free from errors using the validate.py script:
cd /path/to/titanium_mobile/apidoc
python ./validate.pyValidating on Windows
On Windows, as Command Line program cannot handle the UTF-8 characters of the validation report, the following error may be displayed:
UnicodeEncodeError: 'charmap' codec can't encode character u'\u2713' in position 1: character maps to <undefined>A workaround for this is to only display a simple report, using the following command:
cd /path/to/titanium_mobile/apidoc
python validate.py --errors-only --style=simpleIf these commands do not work as a standard user, try running them as a system administrator.
Submitting Contributions
The process for contributing APIDocs is the same as contributing code. Please refer to Git and Github for guidance.