Home

Welcome to the lua-reference-guide wiki!

How to edit/create Lua documentation

The OpenTX Lua interface documentation is written in a format that is compatible with https://www.gitbook.com where the document is also published https://www.gitbook.com/book/opentx/opentx-lua-reference-guide

There are two distinct parts to this documentation repository:

• auto-generated content
• manually generated content

Auto-generated content

Most of the documents here are generated with a special script that parses OpenTX source code, extracts Lua API documentation and outputs gitbook formated pages. The script also looks for any manually created pages that are included in each function documentation (examples, images, etc..).

Each page that is auto-generated has this comment at the begging to remind us not to edit it directly:

<!-- This file was generated by the script. Do not edit it, any changes will be lost! -->

In order to make changes to the contents of such page one has to:

• edit the documentation in OpenTX code
• edit manually created pages that are included in this page (examples, images, ...)

Architecture of auto-generated page

The base of each auto-generated page is a specially formated C comment that resides in one of the OpenTX source files. Each such comment documents one Lua API function. Here is example of playDuration() function description:

/*luadoc
@function playDuration(duration [, hourFormat])

Play a time value (text to speech)

@param duration (number) number of seconds to play. Only integral part is used.

@param hourFormat (number):
 * `0 or not present` play format: minutes and seconds.
 * `!= 0` play format: hours, minutes and seconds.

@status current Introduced in 2.1.0
*/

The auto-generated page will have the same name as the function in this example playDuration.md. The script also looks for and embeds any existing manually created pages/images that it finds:

• <function_name>-example*.md is included verbatim
• <function_name>-example*.png is included as image (linked)
• <function_name>-example*.lua is included and rendered as Lua code example

This enables us to add additional content (such as examples) to the documentation of each function without polluting OpenTX source code with Lua examples and images.

Generation of auto-generated pages

The script that does this is https://github.com/opentx/lua-reference-guide/blob/master/tools/generate-api-docs.py.

There are two sources from which the pages can be generated:

• local repository
• remote official OpenTX repository (preffered)

First option can be used for testing before the changes are actually pushed to the OpenTX repository. The tool is run with the list of all files that contain Lua docs (all files from the radio/src/lua/ that begin with api_):

./tools/generate-api-docs.py ../opentx/radio/src/lua/api_*

To use second option just run the tool without any parameters. It will fetch the latest files from the github:

./tools/generate-api-docs.py 

Testing the book locally

Go into the root directory of this repository and issue command:

gitbook serve

Then open the URL that is returned (after a while) in the browser.

Prerequisites for Ubuntu 16.04

A working installation of gitbook toolchain (for details see https://toolchain.gitbook.com/setup.html). Install following packages:

sudo apt-get install nodejs npm nodejs-legacy

Then install gitbook toolchain:

sudo npm install gitbook-cli -g

Manually generated content

The rest of the pages are manually generated in a text editor or by some other method. The syntax is in Markdown language and can easily be edited with any text editor. WYSIWYG editor is also available on the github but the result (gitbook) can only be seen after the commit of the new text.

Recommended work-flow:

• clone/pull this git repository
• make changes
• update auto-generated pages (if necessary)
• generate gitbook locally and verify that the changes are good
• commit to local git repository
• push the new commit to this repository or make a pull request