Document the Teal workflow

docs/source/reference/lua-scripting/overview.rst

@@ -1,13 +1,20 @@
 Overview of Lua scripting
 #########################
 
+.. toctree::
+    :hidden:
+
+    teal
+
 Language and sandboxing
 =======================
 
 OpenMW supports scripts written in Lua 5.1 with some extensions (see below) from Lua 5.2.
 There are no plans to switch to any newer version of the language, because newer versions are not supported by LuaJIT.
 
-Here are starting points for learning Lua:
+There are also experimental declarations available for Teal, a typed dialect of Lua. see :ref:`Teal` for more details.
+
+Here are some starting points for learning Lua:
 
 - `Programing in Lua <https://www.lua.org/pil/contents.html>`__ (first edition, aimed at Lua 5.0)
 - `Lua 5.1 Reference Manual <https://www.lua.org/manual/5.1/>`__

docs/source/reference/lua-scripting/teal.rst

@@ -0,0 +1,44 @@
+Teal
+####
+
+What is Teal?
+=============
+
+Teal is a typed dialect of Lua. `Teal's Github repository <https://github.com/teal-language/tl>`_.
+
+Teal compiles into Lua, so you can use it in any Lua 5.1+ runtime. If you are familiar with TypeScript, Teal is to Lua what TypeScript is to JavaScript.
+You can find the basics of the syntax and justification for typed Lua in the `Teal tutorial <https://github.com/teal-language/tl/blob/master/docs/tutorial.md>`_.
+
+Teal's syntax is mostly the same as Lua, but with additional type declarations and annotations.
+It will help you catch many mistakes before even running a script, and provide confidence about large code changes.
+
+Using the type checker
+======================
+
+To compile your ``.tl`` files into ``.lua`` files, install `Cyan, Teal's build system <https://github.com/teal-language/cyan>`_.
+
+Create a directory for your project, with a ``tlconfig.lua`` file inside.
+All of your scripts (i. e. the ``scripts`` directory) should be within this directory.
+``tlconfig.lua`` configures the Teal build system and compiler, see the `complete list here <https://github.com/teal-language/tl/blob/master/docs/compiler_options.md>`_.
+
+.. note::
+  You can use ``cyan init`` to set up a directory for a Teal project automatically.
+
+In addition to setting up a build process, you will need the `declaration files for the OpenMW API <https://gitlab.com/OpenMW/openmw/-/jobs/artifacts/master/raw/build_teal.zip?job=Teal>`_.
+Unpack them into a directory of your choice, and add that path to the ``include_dir`` option in your ``tlconfig.lua``. Alternatively, you can add ``-I <my-dcelaration-directory-path>`` as an agument to ``Cyan`` commands.
+
+After everything is ready, run ``cyan build`` in the same directory as ``tlconfig.lua``. It will find all the ``.tl`` files in the ``source_dir``, and put compiled ``.lua`` files at the same relative paths inside ``build_dir``.
+Running ``cyan build`` will also perform a type check, notifying you of any mismatches or mistakes.
+
+.. note::
+  ``source_dir`` and ``build_dir`` can be the same directory. In fact, that is the recommended arrangement, so that it's convenient to include the original sources with your scripts.
+
+IDE support
+===========
+
+Work on `Teal Language Server <https://github.com/teal-language/teal-language-server>`_ is still ongoing, so for now the only supported IDE is `Visual Studio Code <https://code.visualstudio.com/>`_.
+It's available on Windows, Linux and Mac, so most likely you can run it too.
+Teal's extension can be found here: `VSCode Marketplace <https://marketplace.visualstudio.com/items?itemName=pdesaulniers.vscode-teal>`_ (or simply search for "Teal" in the extension UI).
+
+.. note::
+  VSCode also has a web version, but the Teal extension isn't available there.