widelands-dev team mailing list archive

[GunChleoc <fios@xxxxxxxxxxxxxxxxxxx>]

GunChleoc has proposed merging lp:~widelands-dev/widelands/sphinx_changes into lp:widelands.

Commit message:
Started adding World and Tribes to Widelands Scripting Reference.

- World: in-editor help scripts
- Tribes: in-game help scripts, basic tribe definition and building definitions.
- Updated doc/sphinx/README

Requested reviews:
  Widelands Developers (widelands-dev)
Related bugs:
  Bug #1512093 in widelands: "Add tribes directory to developer scripting reference"
  https://bugs.launchpad.net/widelands/+bug/1512093

For more details, see:
https://code.launchpad.net/~widelands-dev/widelands/sphinx_changes/+merge/304751

Started adding World and Tribes to Widelands Scripting Reference.

There is still more work to do (workers, wares etc...), but I think this is growing a bit wordy for reviews. So, more documentation will be added in a later branch.
-- 
Your team Widelands Developers is requested to review the proposed merge of lp:~widelands-dev/widelands/sphinx_changes into lp:widelands.

=== modified file 'data/scripting/editor/format_editor.lua'
--- data/scripting/editor/format_editor.lua	2016-02-10 14:45:46 +0000
+++ data/scripting/editor/format_editor.lua	2016-09-02 09:34:47 +0000
@@ -1,13 +1,13 @@
 -- RST
 -- format_editor.lua
--- ---------------
-
+-- -----------------
+--
 -- Functions used in the ingame editor help windows for formatting the text and pictures.
 
 include "scripting/formatting.lua"
 
 -- RST
--- .. function picture_li(imagepath, text)
+-- .. function:: picture_li(imagepath, text)
 --
 --    Places a paragraph of text to the right of an image
 
@@ -21,7 +21,7 @@
 end
 
 -- RST
--- .. function spacer()
+-- .. function:: spacer()
 --
 --    Adds a little space between two paragraphs
 --
@@ -29,26 +29,3 @@
 function spacer()
    return rt(p("font-size=3", ""))
 end
-
--- RST
--- .. function text_line(t1, t2[, imgstr = nil])
---
---    Creates a line of h3 formatted text followed by normal text and an image.
---
---    :arg t1: text in h3 format.
---    :arg t2: text in p format.
---    :arg imgstr: image aligned right.
---    :returns: header followed by normal text and image.
---
-function text_line(t1, t2, imgstr)
-   if imgstr then
-      return "<rt text-align=left image=" .. imgstr ..
-         " image-align=right><p font-size=13 font-color=D1D1D1>" ..
-         t1 .. "</p><p line-spacing=3 font-size=12>" ..
-         t2 .. "<br></p><p font-size=8> <br></p></rt>"
-   else
-      return "<rt text-align=left><p font-size=13 font-color=D1D1D1>" ..
-         t1 .. "</p><p line-spacing=3 font-size=12>" ..
-         t2 .. "<br></p><p font-size=8> <br></p></rt>"
-   end
-end

=== modified file 'data/scripting/editor/terrain_help.lua'
--- data/scripting/editor/terrain_help.lua	2016-04-02 07:33:57 +0000
+++ data/scripting/editor/terrain_help.lua	2016-09-02 09:34:47 +0000
@@ -1,9 +1,9 @@
 -- RST
 -- terrain_help.lua
--- -------------
-
-
--- This file returns a formatted entry for the terrain help in the editor.
+-- ----------------
+--
+-- This script returns a formatted entry for the terrain help in the editor.
+-- Pass the internal terrain name to the coroutine to select the terrain type.
 
 include "scripting/editor/format_editor.lua"
 

=== modified file 'data/scripting/editor/tree_help.lua'
--- data/scripting/editor/tree_help.lua	2016-04-02 07:33:57 +0000
+++ data/scripting/editor/tree_help.lua	2016-09-02 09:34:47 +0000
@@ -1,8 +1,9 @@
 -- RST
 -- tree_help.lua
--- -------------
-
--- This file returns a formatted entry for the tree help in the editor.
+-- ---------------
+--
+-- This script returns a formatted entry for the tree help in the editor.
+-- Pass the internal tree name to the coroutine to select the tree type.
 
 include "scripting/editor/format_editor.lua"
 

=== modified file 'data/scripting/formatting.lua'
--- data/scripting/formatting.lua	2016-04-02 10:53:01 +0000
+++ data/scripting/formatting.lua	2016-09-02 09:34:47 +0000
@@ -2,7 +2,7 @@
 -- formatting.lua
 -- --------------
 --
--- Function to simplify and unique text formatting in scenarios and help files.
+-- Functions to simplify and unique text formatting in scenarios and help files.
 -- Most of these functions are simple wrapper functions that make working with
 -- widelands rich text formatting system more bearable.
 
@@ -237,3 +237,26 @@
 function dl(dt, dd)
    return b(dt) .. " " .. dd .. "<br>"
 end
+
+-- RST
+-- .. function:: text_line(t1, t2[, imgstr = nil])
+--
+--    Creates a line of h3 formatted text followed by normal text and an image.
+--
+--    :arg t1: text in h3 format.
+--    :arg t2: text in p format.
+--    :arg imgstr: image aligned right.
+--    :returns: header followed by normal text and image.
+--
+function text_line(t1, t2, imgstr)
+   if imgstr then
+      return "<rt text-align=left image=" .. imgstr ..
+         " image-align=right><p font-size=13 font-color=D1D1D1>" ..
+         t1 .. "</p><p line-spacing=3 font-size=12>" ..
+         t2 .. "<br></p><p font-size=8> <br></p></rt>"
+   else
+      return "<rt text-align=left><p font-size=13 font-color=D1D1D1>" ..
+         t1 .. "</p><p line-spacing=3 font-size=12>" ..
+         t2 .. "<br></p><p font-size=8> <br></p></rt>"
+   end
+end

=== modified file 'data/tribes/atlanteans.lua'
--- data/tribes/atlanteans.lua	2016-01-31 21:03:15 +0000
+++ data/tribes/atlanteans.lua	2016-09-02 09:34:47 +0000
@@ -1,5 +1,50 @@
+-- RST
+-- <tribename>.lua
+-- ---------------------
+--
+-- This file contains all the units for a tribe.
+
 dirname = path.dirname(__file__)
 
+-- RST
+-- .. function:: new_tribe(table)
+--
+--    This function adds all units to a tribe.
+--
+--    :arg table: This table contains all the data that the game engine will add to the tribe.
+--                It contains the following entries:
+--
+--    **name**: A string containing the internal name of the tribe.
+--
+--    **animations**: Global animations. Contains subtables for ``frontier`` and ``flag``. Each animation needs the parameters ``pictures`` (table of filenames) and ``hotspot`` (2 integer coordinates), and may also define ``fps`` (integer frames per second).
+--
+--    **roads**: The file paths for the tribes' road textures in 2 subtables ``busy`` and ``normal``
+--
+--    **wares_order**: This defines all the wares that this tribe uses and their display order in the user interface. Each subtable defines a column in the user interface.
+--
+--    **workers_order**:  This defines all the workers that this tribe uses and their display order in the user interface. Each subtable defines a column in the user interface.
+--
+--    **immovables**: This defines all the immovables that this tribe uses.
+--
+--    **buildings**: This defines all the buildings that this tribe uses and their display order in the user interface.
+--
+--    **ship_names**: A list of strings with ship names presented to the user - be creative :)
+--
+--    **builder**:  The internal name of the tribe's builder. This unit needs to be defined in the ``workers_order`` table too.
+--
+--    **carrier**:  The internal name of the tribe's carrier. This unit needs to be defined in the ``workers_order`` table too.
+--
+--    **carrier2**:  The internal name of the tribe's beast of burden. This unit needs to be defined in the ``workers_order`` table too.
+--
+--    **geologist**:  The internal name of the tribe's geologist. This unit needs to be defined in the ``workers_order`` table too.
+--
+--    **soldier**: The internal name of the tribe's soldier. This unit needs to be defined in the ``workers_order`` table too.
+--
+--    **ship**: The internal name of the tribe's ship.
+--
+--    **headquarters**: The internal name of the tribe's headquarters building. This unit needs to be defined in the ``buildings`` table too.
+--
+--    **port**: The internal name of the tribe's port building. This unit needs to be defined in the ``buildings`` table too.
 tribes:new_tribe {
    name = "atlanteans",
 

=== modified file 'data/tribes/buildings/militarysites/atlanteans/castle/helptexts.lua'
--- data/tribes/buildings/militarysites/atlanteans/castle/helptexts.lua	2015-12-02 04:01:09 +0000
+++ data/tribes/buildings/militarysites/atlanteans/castle/helptexts.lua	2016-09-02 09:34:47 +0000
@@ -1,26 +1,68 @@
+-- RST
+-- Building Helptexts
+-- ------------------
+--
+-- Each building has a ``helptexts.lua`` script, which is located in the same directory as its ``init.lua`` script.
+-- The functions in this file return texts that are used for buildings by the Tribal Encyclopedia.
+--
+-- See also the helper functions in ``scripting/help/global_helptexts.lua``
+--
+
 -- This include can be removed when all help texts have been defined.
 include "tribes/scripting/help/global_helptexts.lua"
 
+-- RST
+-- .. function:: building_helptext_lore()
+--
+--    Returns a localized string with a lore helptext for this building.
+--    If you don't have a lore text yet, use ``no_lore_text_yet()`` from the ``global_helptexts.lua`` script.
+--
+--    :returns: Localized lore text
 function building_helptext_lore()
    -- TRANSLATORS#: Lore helptext for a building
    return no_lore_text_yet()
 end
 
+-- RST
+-- .. function:: building_helptext_lore_author()
+--
+--    Returns a localized string with a fictional author for the lore helptext for this building. The returned string can be empty.
+--    If you don't have an author yet, use ``no_lore_author_text_yet()`` from the ``global_helptexts.lua`` script.
+--
+--    :returns: Localized lore author or empty string.
 function building_helptext_lore_author()
    -- TRANSLATORS#: Lore author helptext for a building
    return no_lore_author_text_yet()
 end
 
+-- RST
+-- .. function:: building_helptext_purpose()
+--
+--    Returns a localized string with a purpose helptext for this building. This should be individually defined for all buildings. You can use ``no_purpose_text_yet()`` from the ``global_helptexts.lua`` script if you're not ready to define this yet.
+--
+--    :returns: Localized purpose text
 function building_helptext_purpose()
    -- TRANSLATORS: Purpose helptext for a building
    return pgettext("building", "Garrisons soldiers to expand your territory.")
 end
 
+-- RST
+-- .. function:: building_helptext_note()
+--
+--    Returns a localized string with a note that is added to the purpose. This can be empty.
+--
+--    :returns: Localized note text or empty string.
 function building_helptext_note()
    -- TRANSLATORS: Note helptext for a building
    return pgettext("building", "If you’re low on soldiers to occupy new military sites, use the downward arrow button to decrease the capacity. You can also click on a soldier to send him away.")
 end
 
+-- RST
+-- .. function:: building_helptext_performance()
+--
+--    Returns a localized string with a performance helptext for this building. You can use ``no_purpose_text_yet()`` from the ``global_helptexts.lua`` script if the performance hasn't been calculated yet. Leave empty when this isn't applicable (e.g. for militarysites or warehouses).
+--
+--    :returns: Localized performance text or empty string.
 function building_helptext_performance()
    -- TRANSLATORS#: Performance helptext for a building
    return ""

=== modified file 'data/tribes/buildings/militarysites/atlanteans/castle/init.lua'
--- data/tribes/buildings/militarysites/atlanteans/castle/init.lua	2015-12-28 22:02:27 +0000
+++ data/tribes/buildings/militarysites/atlanteans/castle/init.lua	2016-09-02 09:34:47 +0000
@@ -1,5 +1,63 @@
+-- RST
+-- Military Sites
+-- --------------
+--
+-- Militarysites are a type of building that can house soldiers and that expand the players' terrain.
+-- They can also be attacked.
+--
+-- Militarysites are defined in
+-- ``data/tribes/buildings/militarysites/<tribe_name>/<building_name>/init.lua``.
+-- The building will also need its help texts, which are defined in
+-- ``data/tribes/buildings/militarysites/<tribe_name>/<building_name>/helptexts.lua``
+
 dirname = path.dirname(__file__)
 
+-- RST
+-- .. function:: new_militarysite_type(table)
+--
+--    This function adds the definition of a military site building to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add to this building.
+--                It contains the following entries:
+--
+--    **msgctxt**: The context that Gettext will use to disambiguate the translations for strings in this table.
+--
+--    **name**: A string containing the internal name of this building.
+--
+--    **descname**: The translatable display name. use ``pgettext`` with the ``msgctxt`` above to fetch the string.
+--
+--    **helptext_script**: The full path to the ``helptexts.lua`` script for this building.
+--
+--    **icon**: The full path to the menu icon for this building.
+--
+--    **size**: The size of this building: ``"small"``, ``"medium"``, or ``"big"``.
+--
+--    **buildcost**: A table with the wares used to build this building, containing warename - amount pairs, e.g. ``buildcost = { log = 4, granite = 2 }``.
+--
+--    **return_on_dismantle**: The wares that this building will give back to the player when it is dismantled, e.g. ``buildcost = { log = 2, granite = 1 }``.
+--
+--    **enhancement_cost**: The wares needed to upgrade this building, e.g. ``enhancement_cost = { log = 1, granite = 1 }``.
+--
+--    **return_on_dismantle_on_enhanced**: The wares that this enhanced building will give back to the player when it is dismantled, e.g. ``return_on_dismantle_on_enhanced = { granite = 1 }``.
+--
+--    **animations**: A table containing all animations for this building.
+--
+--    **aihints**: A list of name - value pairs with hints for the AI.
+--
+--    **max_soldiers**: The maximum number of solders that can be garrisoned at this building.
+--
+--    **heal_per_second**: The number of health points that a garrisoned soldier will heal each second.
+--
+--    **conquers**: The conquer radius for this building.
+--
+--    **prefer_heroes**: Whether this building prefers heroes or rookies per default. Set to ``true`` or ``false``.
+--
+--    **messages**: Messages that this building will send to the user. The following messages need to ne defined:
+--         * *occupied*: Shown when your soldiers occupy a new building
+--         * *aggressor*: Shown when this building sees enemy soldiers
+--         * *attack*: Shown when this building is being attacked by an enemy
+--         * *defeated_enemy*: Shown when you lose this building to an enemy
+--         * *defeated_you*: Shown when you take this building from an enemy
 tribes:new_militarysite_type {
    msgctxt = "atlanteans_building",
    name = "atlanteans_castle",

=== modified file 'data/tribes/buildings/partially_finished/constructionsite/init.lua'
--- data/tribes/buildings/partially_finished/constructionsite/init.lua	2015-12-11 16:54:00 +0000
+++ data/tribes/buildings/partially_finished/constructionsite/init.lua	2016-09-02 09:34:47 +0000
@@ -1,5 +1,44 @@
+-- RST
+-- Construction Sites
+-- ------------------
+--
+-- The constructionsite is a special building.
+-- It is a building site where a building is being constructed.
+-- Just like the dismantlesite, it is defined only once for all tribes.
+--
+-- The constructionsite is defined in
+-- ``buildings/partially_finished/constructionsite/init.lua``.
+-- The building will also need its help texts, which are defined in
+-- ``buildings/partially_finished/constructionsite/helptexts.lua``
+
 dirname = path.dirname(__file__)
 
+-- RST
+-- .. function:: new_constructionsite_type(table)
+--
+--    This function adds the definition of the construction site building to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add to this building.
+--                It contains the following entries:
+--
+--    **msgctxt**: The context that Gettext will use to disambiguate the translations for strings in this table.
+--
+--    **name**: A string containing the internal name of this building.
+--
+--    **descname**: The translatable display name. use ``pgettext`` with the ``msgctxt`` above to fetch the string.
+--
+--    **helptext_script**: The full path to the ``helptexts.lua`` script for this building.
+--
+--    **icon**: The full path to the menu icon for this building.
+--
+--    **vision_range**: The size of the radious that the building sees.
+--
+--    **size**: The size of this building: ``"small"``, ``"medium"``, or ``"big"``.
+--
+--    **animations**: A table containing all animations for this building.
+--
+--    **aihints**: A list of name - value pairs with hints for the AI.
+--
 tribes:new_constructionsite_type {
    msgctxt = "building",
    name = "constructionsite",

=== modified file 'data/tribes/buildings/partially_finished/dismantlesite/init.lua'
--- data/tribes/buildings/partially_finished/dismantlesite/init.lua	2015-12-11 16:54:00 +0000
+++ data/tribes/buildings/partially_finished/dismantlesite/init.lua	2016-09-02 09:34:47 +0000
@@ -1,5 +1,44 @@
+-- RST
+-- Dismantle Sites
+-- ---------------
+--
+-- The dismantlesite is a special building.
+-- It is a building site where a building is being dismantled.
+-- Just like the constructionsite, it is defined only once for all tribes.
+--
+-- The dismantlesite is defined in
+-- ``buildings/partially_finished/dismantlesite/init.lua``.
+-- The building will also need its help texts, which are defined in
+-- ``buildings/partially_finished/dismantlesite/helptexts.lua``
+
 dirname = path.dirname(__file__)
 
+-- RST
+-- .. function:: new_dismantlesite_type(table)
+--
+--    This function adds the definition of the dismantle site building to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add to this building.
+--                It contains the following entries:
+--
+--    **msgctxt**: The context that Gettext will use to disambiguate the translations for strings in this table.
+--
+--    **name**: A string containing the internal name of this building.
+--
+--    **descname**: The translatable display name. use ``pgettext`` with the ``msgctxt`` above to fetch the string.
+--
+--    **helptext_script**: The full path to the ``helptexts.lua`` script for this building.
+--
+--    **icon**: The full path to the menu icon for this building.
+--
+--    **vision_range**: The size of the radious that the building sees.
+--
+--    **size**: The size of this building: ``"small"``, ``"medium"``, or ``"big"``.
+--
+--    **animations**: A table containing all animations for this building.
+--
+--    **aihints**: A list of name - value pairs with hints for the AI.
+--
 tribes:new_dismantlesite_type {
    msgctxt = "building",
    name = "dismantlesite",

=== modified file 'data/tribes/buildings/productionsites/atlanteans/armorsmithy/init.lua'
--- data/tribes/buildings/productionsites/atlanteans/armorsmithy/init.lua	2015-12-11 16:54:00 +0000
+++ data/tribes/buildings/productionsites/atlanteans/armorsmithy/init.lua	2016-09-02 09:34:47 +0000
@@ -1,5 +1,73 @@
+-- RST
+-- Production Sites
+-- ----------------
+--
+-- Productionsites are a type of building where wares are being consumed to
+-- produce other wares, or to produce workers.
+-- They also have workers working at them.
+--
+-- Productionsites are defined in
+-- ``data/tribes/buildings/productionsites/<tribe_name>/<building_name>/init.lua``.
+-- The building will also need its help texts, which are defined in
+-- ``data/tribes/buildings/productionsites/<tribe_name>/<building_name>/helptexts.lua``
+
+
 dirname = path.dirname(__file__)
 
+-- RST
+-- .. function:: new_productionsite_type(table)
+--
+--    This function adds the definition of a production site building to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add to this building.
+--                It contains the following entries:
+--
+--    **msgctxt**: The context that Gettext will use to disambiguate the translations for strings in this table.
+--
+--    **name**: A string containing the internal name of this building.
+--
+--    **descname**: The translatable display name. use ``pgettext`` with the ``msgctxt`` above to fetch the string.
+--
+--    **helptext_script**: The full path to the ``helptexts.lua`` script for this building.
+--
+--    **icon**: The full path to the menu icon for this building.
+--
+--    **size**: The size of this building: ``"small"``, ``"medium"``, ``"big"`` or ``"mine"``.
+--
+--    **buildcost**: A table with the wares used to build this building, containing warename - amount pairs, e.g. ``buildcost = { log = 4, granite = 2 }``.
+--
+--    **return_on_dismantle**: The wares that this building will give back to the player when it is dismantled, e.g. ``buildcost = { log = 2, granite = 1 }``.
+--
+--    **enhancement_cost**: The wares needed to upgrade this building, e.g. ``enhancement_cost = { log = 1, granite = 1 }``.
+--
+--    **return_on_dismantle_on_enhanced**: The wares that this enhanced building will give back to the player when it is dismantled, e.g. ``return_on_dismantle_on_enhanced = { granite = 1 }``.
+--
+--    **animations**: A table containing all animations for this building.
+--
+--    **aihints**: A list of name - value pairs with hints for the AI.
+--
+--    **working_positions**: The name and amount for each worker type working at this building.
+--
+--    **inputs**: The name and amount for each ware input queue.
+--
+--    **outputs**: The wares/workers produced by this building.
+--
+--    **programs**: The production site programs that define what preconditions
+--    a building needs to fulfil in order to produce its wares and how it's done,
+--    including any animations and sounds played. See also :doc:`productionsite_program`.
+--
+--    **out_of_resource_notification**: This optional table defines the message
+--    sent by the productionsite to the player if it has run out of a resource to
+--    collect. Table keys are:
+--
+--        *title*: A concise message title for the list in the inbox.
+--
+--        *heading*: A longer version of the title, shown in the message body.
+--
+--        *message*: The actual message. Translation needs to be fetched with pgettext.
+--
+--        *productivity_threshold*: An optional int value in percent to trigger the message.
+--
 tribes:new_productionsite_type {
    msgctxt = "atlanteans_building",
    name = "atlanteans_armorsmithy",

=== modified file 'data/tribes/buildings/trainingsites/atlanteans/dungeon/init.lua'
--- data/tribes/buildings/trainingsites/atlanteans/dungeon/init.lua	2016-01-02 21:39:43 +0000
+++ data/tribes/buildings/trainingsites/atlanteans/dungeon/init.lua	2016-09-02 09:34:47 +0000
@@ -1,5 +1,53 @@
+-- RST
+-- Training Sites
+-- --------------
+--
+-- Trainingsites are a special type of productionsite building where soldiers are
+-- housed and wares are being consumed to train the soldiers to better levels.
+-- They also have workers working at them.
+--
+-- Trainingsites are defined in
+-- ``data/tribes/buildings/trainingsites/<tribe_name>/<building_name>/init.lua``.
+-- The building will also need its help texts, which are defined in
+-- ``data/tribes/buildings/trainingsites/<tribe_name>/<building_name>/helptexts.lua``
+
 dirname = path.dirname(__file__)
 
+-- RST
+-- .. function:: new_trainingsite_type(table)
+--
+--    This function adds the definition of a training site building to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add to this building.
+--                It contains everything that a productionsite contains, plus the following entries:
+--
+--    **soldier_capacity**: An int describing how many soldiers this building can house.
+--
+--    **trainer_patience**: An int describing how patient the trainer is.
+--    If trainer patience runs out, a soldier will be kicked out.
+--
+--    **soldier attack**: A table describing what is needed to train a soldier in attack.
+--    It contains the following entries:
+--
+--        *min_level*: The minimum attack level that a soldier needs before it
+--        can be trained in attack at this training site.
+--
+--        *max_level*: The maximum level of attack that a soldier can be trained in.
+--
+--        *food*: A table with the types food needed to train a soldier in attack.
+--        It contains subtables with alternatives, e.g. ``{"fish", "meat"}``
+--        means that fish OR meat is needed, ``{"fish"}, {"meat"}`` means that fish
+--        AND meat are needed.
+--
+--        *weapons*: A table with the list of weapons that are used for attack
+--        training at the various levels.
+--
+--   **soldier defense**: Just like ``soldier attack``, but for defense training
+--
+--   **soldier health**: Just like ``soldier attack``, but for health training
+--
+--   **soldier evade**: Just like ``soldier attack``, but for evade training
+--
 tribes:new_trainingsite_type {
    msgctxt = "atlanteans_building",
    name = "atlanteans_dungeon",

=== modified file 'data/tribes/buildings/warehouses/atlanteans/headquarters/init.lua'
--- data/tribes/buildings/warehouses/atlanteans/headquarters/init.lua	2015-12-11 16:54:00 +0000
+++ data/tribes/buildings/warehouses/atlanteans/headquarters/init.lua	2016-09-02 09:34:47 +0000
@@ -1,5 +1,59 @@
+-- RST
+-- Headquarters, Warehouses and Ports
+-- ----------------------------------
+--
+-- Warehouses are a type of building where wares and workers are being stored
+-- that aren't currently needed at another building.
+-- Warehouses can also be one of two special types: a headquarters or a port.
+-- A *headquarters* is also the tribe's main building.
+-- A *port* can only be built on a designated port space and allows transferring
+-- wares by sea and starting expeditions.
+--
+-- Warehouses are defined in
+-- ``data/tribes/buildings/warehouses/<tribe_name>/<building_name>/init.lua``.
+-- The building will also need its help texts, which are defined in
+-- ``data/tribes/buildings/warehouses/<tribe_name>/<building_name>/helptexts.lua``
+
 dirname = path.dirname(__file__)
 
+-- RST
+-- .. function:: new_warehouse_type(table)
+--
+--    This function adds the definition of a warehouse building to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add to this building.
+--                It contains the following entries:
+--
+--    **msgctxt**: The context that Gettext will use to disambiguate the translations for strings in this table.
+--
+--    **name**: A string containing the internal name of this building.
+--
+--    **descname**: The translatable display name. use ``pgettext`` with the ``msgctxt`` above to fetch the string.
+--
+--    **helptext_script**: The full path to the ``helptexts.lua`` script for this building.
+--
+--    **icon**: The full path to the menu icon for this building.
+--
+--    **size**: The size of this building: ``"small"``, ``"medium"``, ``"big"`` or ``"port"``.
+--
+--    **destructible**: Set this to ``false`` for headquarters, leave blank otherwise.
+--
+--    **buildcost**: A table with the wares used to build this building, containing warename - amount pairs, e.g. ``buildcost = { log = 4, granite = 2 }``. If this table isn't defined, the building will be a headquarters.
+--
+--    **return_on_dismantle**: The wares that this building will give back to the player when it is dismantled, e.g. ``buildcost = { log = 2, granite = 1 }``. If this table isn't defined, the building will be a headquarters.
+--
+--    **enhancement_cost**: The wares needed to upgrade this building, e.g. ``enhancement_cost = { log = 1, granite = 1 }``. If this table isn't defined, the building will be a headquarters.
+--
+--    **return_on_dismantle_on_enhanced**: The wares that this enhanced building will give back to the player when it is dismantled, e.g. ``return_on_dismantle_on_enhanced = { granite = 1 }``. If this table isn't defined, the building will be a headquarters.
+--
+--    **animations**: A table containing all animations for this building.
+--
+--    **aihints**: A list of name - value pairs with hints for the AI.
+--
+--    **heal_per_second**: The number of health points that a garrisoned soldier will heal each second.
+--
+--    **conquers**: The conquer radius for this building. This is used for headquarters and ports.
+--
 tribes:new_warehouse_type {
    msgctxt = "atlanteans_building",
    name = "atlanteans_headquarters",

=== modified file 'data/tribes/init.lua'
--- data/tribes/init.lua	2015-12-03 19:40:37 +0000
+++ data/tribes/init.lua	2016-09-02 09:34:47 +0000
@@ -1,9 +1,13 @@
+-- RST
+-- init.lua
+-- -----------------
+--
 -- Tribes initialization
 --
--- First the units are loaded, then the tribe descriptions
+-- First the units are loaded, then the tribe descriptions.
 --
 -- All tribes also have some basic information for the load screens
--- and the editor in preload.lua
+-- and the editor in ``preload.lua``.
 --
 -- Basic load order (first wares, then immovables etc.) is important,
 -- because checks will be made in C++.
@@ -13,12 +17,17 @@
 tribes = wl.Tribes()
 
 
--- Adds 6 animations for each walking direction into 'table'. The pictures are
--- searched for in 'dirname'. All files should look like this
--- 'basename'_(e|ne|se|sw|w|nw)_\d+.png.
--- 'hotspot' is the hotspot for blitting.
--- 'animationname' is the name of the animation, e.g. "walkload"
--- 'fps' are the frames per second. Only use this if the animation has more than 1 frame.
+-- RST
+-- .. function:: add_worker_animations(table, animationname, dirname, basename, hotspot, fps)
+--
+--    Adds 6 walk or sail animations - one for each walking direction - to 'table'.
+--
+--    :arg table: A table that the animation data is added to. It may already contain some animations.
+--    :arg animationname: The name of the animation to be added, e.g. ``walkload``.
+--    :arg dirname: The name of the directory where the animation image files are located.
+--    :arg basename: The basename of the animation files. The filenames of the animation files need to have the format ``<basename>_(e|ne|se|sw|w|nw)_\d+.png``
+--    :arg hotspot: The hotspot coordinates for blitting, e.g. ``{ 2, 20 }``.
+--    :arg fps: Frames per second. Only use this if the animation has more than 1 frame, and if you need to deviate from the default frame rate.
 function add_worker_animations(table, animationname, dirname, basename, hotspot, fps)
    if (fps ~= nil) then
       for idx, dir in ipairs{ "ne", "e", "se", "sw", "w", "nw" } do

=== modified file 'data/tribes/preload.lua'
--- data/tribes/preload.lua	2016-03-02 16:28:30 +0000
+++ data/tribes/preload.lua	2016-09-02 09:34:47 +0000
@@ -1,10 +1,13 @@
+-- RST
+-- preload.lua
+-- -----------
+--
+-- This file contains the basic information for all tribes that is
+-- needed before a game is loaded or the editor has been started.
+
 dirname = path.dirname(__file__)
-
 set_textdomain("tribes")
 
--- This file contains the basic information for all tribes that is
--- needed before a game is loaded or the editor has been started.
-
 return {
    -- Basic information for the Barbarian tribe
    {

=== modified file 'data/tribes/scripting/help/building_help.lua'
--- data/tribes/scripting/help/building_help.lua	2016-03-22 07:32:14 +0000
+++ data/tribes/scripting/help/building_help.lua	2016-09-02 09:34:47 +0000
@@ -4,32 +4,11 @@
 
 -- RST
 -- building_help.lua
--- ---------------
-
--- Functions used in the ingame building help windows for formatting the text and pictures.
-
---  =======================================================
---  *************** Basic helper functions ****************
---  =======================================================
-
--- RST
--- .. function text_line(t1, t2[, imgstr = nil])
---
---    Creates a line of h3 formatted text followed by normal text and an image.
---
---    :arg t1: text in h3 format.
---    :arg t2: text in p format.
---    :arg imgstr: image aligned right.
---    :returns: header followed by normal text and image.
---
-function text_line(t1, t2, imgstr)
-   if imgstr then
-      return "<rt text-align=left image=" .. imgstr .. " image-align=right><p font-size=13 font-color=D1D1D1>" ..  t1 .. "</p><p line-spacing=3 font-size=12>" .. t2 .. "<br></p><p font-size=8> <br></p></rt>"
-   else
-      return "<rt text-align=left><p font-size=13 font-color=D1D1D1>" ..  t1 .. "</p><p line-spacing=3 font-size=12>" .. t2 .. "<br></p><p font-size=8> <br></p></rt>"
-   end
-end
-
+-- -----------------
+--
+-- This script returns a formatted entry for the ingame building help.
+-- Pass the internal tribe name and building name to the coroutine to select the
+-- building type.
 
 --  =======================================================
 --  ********** Helper functions for dependencies **********
@@ -174,7 +153,7 @@
 
 
 -- RST
--- .. function building_help_general_string(tribe, building_description)
+-- .. function:: building_help_general_string(tribe, building_description)
 --
 --    Creates the string for the general section in building help
 --
@@ -615,7 +594,7 @@
 
 
 -- RST
--- .. function building_help_crew_string(tribe, building_description)
+-- .. function:: building_help_crew_string(tribe, building_description)
 --
 --    Displays the building's workers with an image and the tool they use
 --
@@ -695,7 +674,7 @@
 
 
 -- RST
--- .. building_help_production_section()
+-- .. function:: building_help_production_section()
 --
 --    Displays the production/performance section with a headline
 --
@@ -712,7 +691,7 @@
 
 
 -- RST
--- .. function building_help(tribe, building_description)
+-- .. function:: building_help(tribe, building_description)
 --
 --    Main function to create a building help string.
 --

=== modified file 'data/tribes/scripting/help/format_help.lua'
--- data/tribes/scripting/help/format_help.lua	2016-02-27 08:43:39 +0000
+++ data/tribes/scripting/help/format_help.lua	2016-09-02 09:34:47 +0000
@@ -1,11 +1,11 @@
-include "scripting/formatting.lua"
-
 -- RST
 -- format_help.lua
--- ---------------
-
+-- -------------------------------------
+--
 -- Functions used in the ingame help windows for formatting the text and pictures.
 
+include "scripting/formatting.lua"
+
 --  =======================================================
 --  *************** Basic helper functions ****************
 --  =======================================================
@@ -63,7 +63,7 @@
 
 
 -- RST
--- .. function help_ware_amount_line(ware_description, amount)
+-- .. function:: help_ware_amount_line(ware_description, amount)
 --
 --    Displays an amount of wares with name and images
 --
@@ -88,7 +88,7 @@
 end
 
 -- RST
--- .. function help_tool_string(tribe, toolname, no_of_workers)
+-- .. function:: help_tool_string(tribe, toolname, no_of_workers)
 --
 --    Displays tools with an intro text and images
 --
@@ -111,12 +111,13 @@
 
 
 -- RST
--- .. function help_consumed_wares(building, program_name)
+-- .. function:: help_consumed_wares(building, program_name)
 --
 --    Returns information for which wares in which amounts are consumed by a produciton program.
 --
 --    :arg tribe: The :class:`LuaBuildingDescription` for the building that runs the program
 --    :arg program_name: The name of the production program that the info is collected for
+--
 --    :returns: A "Ware(s) consumed:" section with image_lines
 --
 function help_consumed_wares(building, program_name)

=== modified file 'data/tribes/scripting/help/global_helptexts.lua'
--- data/tribes/scripting/help/global_helptexts.lua	2016-04-15 16:46:20 +0000
+++ data/tribes/scripting/help/global_helptexts.lua	2016-09-02 09:34:47 +0000
@@ -3,6 +3,14 @@
 --  =======================================================
 
 -- RST
+-- global_helptexts.lua
+-- --------------------
+--
+-- This file contains some default building helptexts that can be used when a more
+-- specific help text hasn't been defined yet. It also contains some global time naming
+-- functions for uniform translations.
+
+-- RST
 -- .. function:: no_lore_text_yet()
 --
 --    Returns a localized string for when no lore helptext has been defined yet.

=== modified file 'data/tribes/scripting/help/ware_help.lua'
--- data/tribes/scripting/help/ware_help.lua	2016-03-22 07:32:14 +0000
+++ data/tribes/scripting/help/ware_help.lua	2016-09-02 09:34:47 +0000
@@ -4,8 +4,10 @@
 -- RST
 -- ware_help.lua
 -- ---------------
-
--- Functions used in the ingame ware help windows for formatting the text and pictures.
+--
+-- This script returns a formatted entry for the ingame ware help.
+-- Pass the internal tribe name and ware name to the coroutine to select the
+-- ware type.
 
 
 --  =======================================================
@@ -13,7 +15,7 @@
 --  =======================================================
 
 -- RST
--- .. function ware_help_general_string(tribe, ware_description)
+-- .. function:: ware_help_general_string(tribe, ware_description)
 --
 --    Displays general info texts about the ware
 --
@@ -35,7 +37,7 @@
 end
 
 -- RST
--- .. function ware_help_producers_string(tribe, ware_description)
+-- .. function:: ware_help_producers_string(tribe, ware_description)
 --
 --    Displays the buildings that produce this ware with information about
 --    wares consumed in their production programs
@@ -101,7 +103,7 @@
 end
 
 -- RST
--- .. function ware_help_consumers_string(tribe, ware_description)
+-- .. function:: ware_help_consumers_string(tribe, ware_description)
 --
 --    Displays the buildings that consume this ware and about
 --    workers that use this ware as a tool

=== modified file 'data/tribes/scripting/help/worker_help.lua'
--- data/tribes/scripting/help/worker_help.lua	2016-04-04 17:04:56 +0000
+++ data/tribes/scripting/help/worker_help.lua	2016-09-02 09:34:47 +0000
@@ -1,15 +1,26 @@
-include "tribes/scripting/help/format_help.lua"
-
 -- RST
 -- worker_help.lua
 -- ---------------
+--
+-- This script returns a formatted entry for the ingame worker help.
+-- Pass the internal tribe name and worker name to the coroutine to select the
+-- worker type.
 
--- Functions used in the ingame worker help windows for formatting the text and pictures.
+include "tribes/scripting/help/format_help.lua"
 
 --  =======================================================
 --  ************* Main worker help functions *************
 --  =======================================================
 
+-- RST
+-- .. function:: worker_help_producers_string(worker_description)
+--
+--    Displays the buildings that can produce the worker
+--
+--    :arg tribe: the worker's tribe from C++.
+--    :arg worker_description: the worker_description from C++.
+--    :returns: Info about buildings that produce this worker
+--
 function worker_help_producers_string(tribe, worker_description)
    local result = ""
    for i, building in ipairs(tribe.buildings) do
@@ -77,7 +88,7 @@
 
 
 -- RST
--- .. function worker_help_employers_string(worker_description)
+-- .. function:: worker_help_employers_string(worker_description)
 --
 --    Displays the buildings where the worker can work
 --
@@ -101,14 +112,15 @@
 
 
 -- RST
--- .. function worker_help_string(worker_description)
+-- .. function:: worker_help_string(worker_description)
 --
 --    Displays the worker with a helptext, an image and the tool used
 --
 --    :arg tribe: The :class:`LuaTribeDescription` for the tribe
 --                that we are displaying this help for.
+
+--    :arg worker_description: the worker_description from C++.
 --
---    :arg worker_description: the worker_description from C++.
 --    :returns: Help string for the worker
 --
 function worker_help_string(tribe, worker_description)

=== modified file 'doc/sphinx/README'
--- doc/sphinx/README	2012-06-20 09:07:10 +0000
+++ doc/sphinx/README	2016-09-02 09:34:47 +0000
@@ -5,15 +5,36 @@
 Widelands. The documentation is generated with sphinx, you need to install this
 if you want to build the documentation (modules py-sphinx or similar).
 
-Building the documentation
---------------------------
-
-First, extract the embedded documentation from the C++ code::
-
+Building the documentation for offline reading
+----------------------------------------------
+
+First, extract the embedded documentation from the C++ and Lua code::
+
+   $ cd doc/sphinx/
    $ ./extract_rst.py
 
 Then, run ``make`` to see your options. Convenient for off-line reading is
-``make html``. 
-
-
+``make html``.
+
+
+Building the documentation for the webserver
+--------------------------------------------
+
+First, extract the embedded documentation from the C++ and Lua code::
+
+   $ cd doc/sphinx/
+   $ ./extract_rst.py
+
+Then build the Sphinx documentation as JSON files:
+
+   $ make json
+
+Then add a Sphinx app to the admin panel in the webserver, if this hasn't been
+done yet:
+
+1. In the "Sphinxdoc" section, add a new app.
+2. Configure the app as follows:
+   Name: Widelands developer documentation
+   Slug: wl
+   Path: <path-to-widelands>/doc/sphinx/build/json/
 

=== modified file 'doc/sphinx/extract_rst.py'
--- doc/sphinx/extract_rst.py	2014-12-01 22:32:03 +0000
+++ doc/sphinx/extract_rst.py	2016-09-02 09:34:47 +0000
@@ -10,23 +10,52 @@
 ###################
 # inputs, outputs #
 ###################
+# These files ar known to have rst comments; cpp files
+# Meaning: (src_file, file_name_to_generate_rst)
 cpp_pairs = (
-    ("src/scripting/lua_root.cc", "autogen_wl.rst"),
-    ("src/scripting/lua_bases.cc", "autogen_wl_bases.rst"),
-    ("src/scripting/lua_editor.cc", "autogen_wl_editor.rst"),
-    ("src/scripting/lua_map.cc", "autogen_wl_map.rst"),
-    ("src/scripting/lua_game.cc", "autogen_wl_game.rst"),
-    ("src/scripting/lua_ui.cc", "autogen_wl_ui.rst"),
-    ("src/scripting/lua_globals.cc", "autogen_globals.rst"),
-)
+    ('src/scripting/lua_root.cc', 'autogen_wl.rst'),
+    ('src/scripting/lua_bases.cc', 'autogen_wl_bases.rst'),
+    ('src/scripting/lua_editor.cc', 'autogen_wl_editor.rst'),
+    ('src/scripting/lua_map.cc', 'autogen_wl_map.rst'),
+    ('src/scripting/lua_game.cc', 'autogen_wl_game.rst'),
+    ('src/scripting/lua_ui.cc', 'autogen_wl_ui.rst'),
+    ('src/scripting/lua_globals.cc', 'autogen_globals.rst'),
+)
+
+# These directories are scanned without knowing which file
+# has rst comments; scan for *.lua files
+# Meaning: (src_dir, file_prefix, toc_name_to_place)
+# The file prefix can be left empty. You can use it to disambiguate if multiple
+# directories contain lua files of the same name (e.g. "init.lua").
+lua_dirs = (
+    ('data/scripting', '', 'auxiliary'),
+    ('data/scripting/win_conditions', '', 'auxiliary'),
+    ('data/scripting/editor', '', 'lua_world'),
+    ('data/tribes', '', 'lua_tribes_defining'),
+    ('data/tribes/scripting', '', 'lua_tribes_other'),
+    ('data/tribes/scripting/mapobject_info', '', 'lua_tribes_other'),
+    ('data/tribes/scripting/help', '', 'lua_tribes_other'),
+    ('data/tribes/buildings/militarysites/atlanteans/castle', 'militarysite', 'lua_tribes_units'),
+    ('data/tribes/buildings/productionsites/atlanteans/armorsmithy', 'productionsite', 'lua_tribes_units'),
+    ('data/tribes/buildings/trainingsites/atlanteans/dungeon', 'trainingsite', 'lua_tribes_units'),
+    ('data/tribes/buildings/warehouses/atlanteans/headquarters', 'warehouse', 'lua_tribes_units'),
+    ('data/tribes/buildings/partially_finished/constructionsite', 'constructionsite', 'lua_tribes_units'),
+    ('data/tribes/buildings/partially_finished/dismantlesite', 'dismantlesite', 'lua_tribes_units'),
+)
+
 
 def _find_basedir():
     """Walk upwards in the directory tree till we are in the base directory of
-    Widelands. Return the base directory and the source/ directory."""
+    Widelands.
+
+    Return the base directory and the source/ directory.
+
+    """
     curdir = p.abspath(p.dirname(__file__))
-    source_dir = p.join(curdir, "source")
-    while not (p.exists(p.join(curdir, "data/tribes")) and p.exists(p.join(curdir, "data/world"))):
+    source_dir = p.join(curdir, 'source')
+    while not (p.exists(p.join(curdir, 'data/tribes')) and p.exists(p.join(curdir, 'data/world'))):
         curdir = p.abspath(p.join(curdir, p.pardir))
+
     return source_dir, curdir
 source_dir, base_dir = _find_basedir()
 
@@ -36,11 +65,10 @@
     Searches for /* RST comments in the given filename, strips the lines
     and prints them out on stdout or writes them to outname.
     """
-    data = open(p.join(base_dir, inname), "r").read()
-
+    data = open(p.join(base_dir, inname), 'r').read()
     res = re.findall(r"\s*/\* RST\s(.*?)\*/", data, re.M | re.DOTALL)
 
-    output = ""
+    output = ''
     for r in res:
         r = r.expandtabs(4)
         output += r + '\n'
@@ -48,46 +76,82 @@
     if output.strip():
         out = sys.stdout
         if outname is not None:
-            out = open(p.join(source_dir, outname), "w")
-        out.write(output)
-
-def extract_rst_from_lua(inname):
-    """
-    Searches for /* RST comments in the given filename, strips the lines
-    and prints them out on stdout or writes them to outname.
-    """
-    data = open(p.join(base_dir, inname), "r").read()
-
-    res = re.findall(r"-- RST\s(.*?)(?:^(?!--))", data, re.M | re.DOTALL)
-
-    outname = "autogen_aux_%s.rst" % os.path.basename(os.path.splitext(inname)[0])
-    outname = p.join(source_dir, outname)
-
-    output = ""
-    for r in res:
-        r = re.subn(re.compile(r'^-- ?', re.M | re.DOTALL), "", r)[0]
-        output += r + '\n'
-
-    if output.strip():
-        out = sys.stdout if not outname else open(outname, "w")
-        out.write(output)
-        return os.path.basename(outname)
-
-def replace_auxilary_toc(aux_fns):
-    aux_in = open(p.join(source_dir, "auxiliary.rst.in"), "r").read()
-    aux_in = aux_in.replace("REPLACE_ME",
-                '\n'.join('   ' + fn for fn in aux_fns))
-    open(p.join(source_dir, "auxiliary.rst"), "w").write(aux_in)
+            out = open(p.join(source_dir, outname), 'w')
+        out.write(output)
+
+
+def extract_rst_from_lua(directory, file_prefix, toc):
+    """
+    Searches for files with /* RST comments in the given directory, strips the lines
+    and writes them to a file (each found file gets a new 'file.rst'). Returns a list
+    with produced files for this directory.
+    """
+    # List to contain all created files
+    rst_file_names = []
+    # Find lua files and search for RST comments
+    for filename in glob(p.join(base_dir, directory, '*.lua')):
+        with open(p.join(base_dir, filename), 'r') as f:
+            data = f.read()
+
+        res = re.findall(r"-- RST\s(.*?)(?:^(?!--))", data, re.M | re.DOTALL)
+
+        if res:
+            # File with RST commet found
+            if file_prefix:
+                toc = file_prefix + '_' + toc
+            outname = 'autogen_' + toc + '_%s.rst' % os.path.basename(
+                os.path.splitext(filename)[0])
+            rst_file_names.append(outname)
+            outname = p.join(source_dir, outname)
+
+            output = ''
+            for r in res:
+                r = re.subn(re.compile(r'^-- ?', re.M | re.DOTALL), '', r)[0]
+                output += r + '\n'
+
+            if output.strip():
+                out = sys.stdout if not outname else open(outname, 'w')
+                out.write(output)
+
+    return rst_file_names
+
+
+def replace_tocs(toc_rst_dict):
+    """Open predefined toc files, add the produced filenames from
+    extract_rst_from_lua() and store it as regular .rst file."""
+    for toc_name, f_names in toc_rst_dict.items():
+
+        # Open original toc file
+        with open(p.join(source_dir, toc_name + '.rst.org'), 'r') as f:
+            f_content = f.read()
+
+        # Add the names to the content of original toc
+        f_content = f_content.replace('REPLACE_ME',
+                                      '\n'.join('   ' + name for name in f_names))
+
+        # Save modified content as new file
+        open(p.join(source_dir, 'autogen_toc_' +
+                    toc_name + '.rst'), 'w').write(f_content)
 
 if __name__ == '__main__':
     def main():
         for inf, outf in cpp_pairs:
             extract_rst_from_cpp(inf, outf)
 
-        replace_auxilary_toc(
-            filter(lambda a: a, [
-                extract_rst_from_lua(i) for i in glob(p.join(base_dir, "data/scripting", "*.lua"))
-            ])
-        )
+        # Search the given dirs for rst-comments in every lua files
+        # Store key:value as toc:list_of_files
+        toc_fnames = {}
+        for directory, file_prefix, toc in lua_dirs:
+            rst_file_names = extract_rst_from_lua(directory, file_prefix, toc)
+            if rst_file_names:
+                if toc in toc_fnames:
+                    # toc key exists, extend the value list
+                    toc_fnames[toc].extend(rst_file_names)
+                else:
+                    # no toc found, create it and add value list
+                    toc_fnames[toc] = rst_file_names
+
+        # Replace the predefined tocs with all found files
+        replace_tocs(toc_fnames)
 
     main()

=== renamed file 'doc/sphinx/source/auxiliary.rst.in' => 'doc/sphinx/source/auxiliary.rst.org'
--- doc/sphinx/source/auxiliary.rst.in	2014-12-01 16:28:26 +0000
+++ doc/sphinx/source/auxiliary.rst.org	2016-09-02 09:34:47 +0000
@@ -2,11 +2,11 @@
 =================
 
 Some Lua scripts come bundled with Widelands (in the ``data/scripting/``
-directory).  They can be imported in any script by the :func:`use` function
-using "aux" as namespace. Most of those scripts provide some convenience
-functionality around the core functions that are easier to use or offer more
-flexibility. All functions are imported into the global namespace if not
-otherwise stated. All auxiliary scripts are documented in this section.
+directory). They can be imported in any script by calling :func:`include`,
+followed by the path relative to the ``data`` directory. Most of these scripts
+provide some convenience functionality around the core functions that are easier
+to use or offer more flexibility. All functions are imported into the global
+namespace. All auxiliary scripts are documented in this section.
 
 
 .. toctree::

=== added file 'doc/sphinx/source/lua_tribes.rst'
--- doc/sphinx/source/lua_tribes.rst	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/lua_tribes.rst	2016-09-02 09:34:47 +0000
@@ -0,0 +1,14 @@
+Scripts for Tribes
+==================
+
+All tribes and their units are defined by Lua scripting files which are located
+in ``data/tribes``.
+
+.. toctree::
+   :maxdepth: 2
+
+   autogen_toc_lua_tribes_defining
+   autogen_toc_lua_tribes_units
+   autogen_toc_lua_tribes_other
+
+

=== added file 'doc/sphinx/source/lua_tribes_defining.rst.org'
--- doc/sphinx/source/lua_tribes_defining.rst.org	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/lua_tribes_defining.rst.org	2016-09-02 09:34:47 +0000
@@ -0,0 +1,19 @@
+Defining Tribes
+===============
+
+Each tribe is bootstrapped with the following scripts:
+
+* ``data/tribes/init.lua``: This file loads all the scripts that define the
+  tribes. So, if you add a new tribe or a new unit to a tribe, it needs to be
+  listed in this file.
+* ``data/tribes/preload.lua``: Provides basic information about all available
+  tribes to the game launching screens. The player won't be able to select a
+  tribe without it being defined in this file.
+* ``data/tribes/<tribe name>.lua``: These scripts tell the engine which units
+  belong to each tribe. They also define some global animated images for each
+  tribe (flags, borders, roads).
+
+.. toctree::
+   :maxdepth: 3
+
+REPLACE_ME

=== added file 'doc/sphinx/source/lua_tribes_other.rst.org'
--- doc/sphinx/source/lua_tribes_other.rst.org	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/lua_tribes_other.rst.org	2016-09-02 09:34:47 +0000
@@ -0,0 +1,22 @@
+Other Scripts
+=============
+
+The ``data/tribes/scripting`` directory provides some global scripts related to
+the tribes. It contains the following subdirectories:
+
+* ``data/tribes/scripting/help``: These scripts load all information used by the
+  in-game help ('Tribal Encyclopedia'). Unit-specific help is loaded with the
+  help of each unit's ``helptexts.lua`` script.
+* ``data/tribes/scripting/mapobject_info``: These scripts are used to generate
+  help information for the `Encyclopedia <https://wl.widelands.org/encyclopedia/>`_
+  on our website. Again, unit-specific help is loaded with the help of each
+  unit's ``helptexts.lua`` script.
+* ``data/tribes/scripting/starting_conditions``: Contains a subdirectory with
+  the game starting conditions available for each tribe. These scripts need to
+  be listed in ``data/tribes/preload.lua`` in order for Widelands to find them.
+
+
+.. toctree::
+   :maxdepth: 3
+
+REPLACE_ME

=== added file 'doc/sphinx/source/lua_tribes_units.rst.org'
--- doc/sphinx/source/lua_tribes_units.rst.org	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/lua_tribes_units.rst.org	2016-09-02 09:34:47 +0000
@@ -0,0 +1,18 @@
+Defining Units
+==============
+
+A tribe can have the following types of units: buildings (militarysites,
+partially_finished, productionsites, trainingsites and warehouses; headquarters
+are a special case of warehouse), immovables, workers, wares, and a ship.
+
+The definitions for the tribes' units are located in the subdirectories of
+``data/tribes``. Each unit needs to have an ``init.lua`` and a ``helptexts.lua``
+file. The ``init.lua`` script will load the unit to be used in the game, and
+``helptexts.lua`` will provide the information used by the in-game help
+('Tribal Encyclopedia') and by our website's online
+`Encyclopedia <https://wl.widelands.org/encyclopedia/>`_.
+
+.. toctree::
+   :maxdepth: 3
+
+REPLACE_ME

=== added file 'doc/sphinx/source/lua_world.rst.org'
--- doc/sphinx/source/lua_world.rst.org	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/lua_world.rst.org	2016-09-02 09:34:47 +0000
@@ -0,0 +1,22 @@
+Scripts for World
+=================
+
+All world elements for Widelands are defined in ``data/world``. There are 2 main
+scripts:
+
+* ``data/world/init.lua``: This file lists all scripts that define the world
+  elements such as critters, immovables (including trees), resources and
+  terrains. It bootstraps the world used in our maps and also defines the editor
+  categories.
+* ``data/world/map_generation.lua``: This file is used by the map generator.
+  You can ignore it while designing your world, but you can add new elements to
+  be included in automatically generated maps if you want.
+
+Critters, immovables, resources and terrains are defined in their respective
+``init.lua`` script files - each world element has its own except for the
+terrains, which have a common ``init.lua`` file.
+
+.. toctree::
+   :maxdepth: 3
+
+REPLACE_ME

=== modified file 'doc/sphinx/source/reference.rst'
--- doc/sphinx/source/reference.rst	2012-06-20 09:07:10 +0000
+++ doc/sphinx/source/reference.rst	2016-09-02 09:34:47 +0000
@@ -3,6 +3,8 @@
 
 .. toctree::
    :maxdepth: 3
- 
+
    core
-   auxiliary
+   autogen_toc_lua_world
+   lua_tribes
+   autogen_toc_auxiliary