Merge lp:~widelands-dev/widelands/sphinx-buildings into lp:widelands

[GunChleoc]

Restructured and enhanced the Buildings documentation.

[bunnybot (widelandsofficial)]

Continuous integration builds have changed state:

Travis build 1417. State: passed. Details: https://travis-ci.org/widelands/widelands/builds/168569023.
Appveyor build 1258. State: success. Details: https://ci.appveyor.com/project/widelands-dev/widelands/build/_widelands_dev_widelands_sphinx_buildings-1258.

[bunnybot (widelandsofficial)]

Continuous integration builds have changed state:

Travis build 1443. State: passed. Details: https://travis-ci.org/widelands/widelands/builds/170385418.
Appveyor build 1286. State: failed. Details: https://ci.appveyor.com/project/widelands-dev/widelands/build/_widelands_dev_widelands_sphinx_buildings-1286.

[bunnybot (widelandsofficial)]

Continuous integration builds have changed state:

Travis build 1571. State: failed. Details: https://travis-ci.org/widelands/widelands/builds/172861819.
Appveyor build 1409. State: success. Details: https://ci.appveyor.com/project/widelands-dev/widelands/build/_widelands_dev_widelands_sphinx_buildings-1409.

[GunChleoc (gunchleoc)]

I need this for other branches, so I'm gonna merge.

@bunnybot merge

=== modified file 'data/tribes/atlanteans.lua'
--- data/tribes/atlanteans.lua	2016-09-27 06:30:47 +0000
+++ data/tribes/atlanteans.lua	2016-11-03 07:38:41 +0000
@@ -1,4 +1,6 @@
 -- RST
+-- .. _lua_tribes_<tribename>.lua:
+--
 -- <tribename>.lua
 -- ---------------------
 --
@@ -7,7 +9,7 @@
 dirname = path.dirname(__file__)
 
 -- RST
--- .. function:: new_tribe(table)
+-- .. function:: new_tribe{table}
 --
 --    This function adds all units to a tribe.
 --

=== modified file 'data/tribes/buildings/militarysites/atlanteans/castle/helptexts.lua'
--- data/tribes/buildings/militarysites/atlanteans/castle/helptexts.lua	2016-09-02 08:27:34 +0000
+++ data/tribes/buildings/militarysites/atlanteans/castle/helptexts.lua	2016-11-03 07:38:41 +0000
@@ -1,68 +1,29 @@
--- 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``
---
+-- The helptext documentation is located in /doc/sphinx/lua_tribes_buildings_rst.org
 
 -- 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	2016-09-22 16:45:02 +0000
+++ data/tribes/buildings/militarysites/atlanteans/castle/init.lua	2016-11-03 07:38:41 +0000
@@ -1,4 +1,6 @@
 -- RST
+-- .. _lua_tribes_buildings_militarysites:
+--
 -- Military Sites
 -- --------------
 --
@@ -13,51 +15,37 @@
 dirname = path.dirname(__file__)
 
 -- RST
--- .. function:: new_militarysite_type(table)
+-- .. 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
+--                In addition to the :ref:`lua_tribes_buildings_common`, it contains the following entries:
+--
+--    **max_soldiers**
+--        *Mandatory*. The maximum number of solders that can be garrisoned at this building.
+--
+--    **heal_per_second**
+--        *Mandatory*. The number of health points that a garrisoned soldier will heal each second.
+--
+--    **conquers**
+--        *Mandatory*. The conquer radius for this building.
+--
+--    **prefer_heroes**
+--        *Mandatory*. Whether this building prefers heroes or rookies per default.
+--        Set to ``true`` or ``false``.
+--
+--    **messages**
+--        *Mandatory*. Messages that this building will send to the user. There are 5 messages,
+--        defined like this::
+--
+--            messages = {
+--                occupied = _"Your soldiers have occupied your fortress.",
+--                aggressor = _"Your fortress discovered an aggressor.",
+--                attack = _"Your fortress is under attack.",
+--                defeated_enemy = _"The enemy defeated your soldiers at the fortress.",
+--                defeated_you = _"Your soldiers defeated the enemy at the fortress."
+--            }
 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	2016-09-22 16:45:02 +0000
+++ data/tribes/buildings/partially_finished/constructionsite/init.lua	2016-11-03 07:38:41 +0000
@@ -1,4 +1,6 @@
 -- RST
+-- .. _lua_tribes_buildings_constructionsites:
+--
 -- Construction Sites
 -- ------------------
 --
@@ -14,30 +16,12 @@
 dirname = path.dirname(__file__)
 
 -- RST
--- .. function:: new_constructionsite_type(table)
+-- .. 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.
+--                It only contains :ref:`lua_tribes_buildings_common`.
 --
 tribes:new_constructionsite_type {
    msgctxt = "building",

=== modified file 'data/tribes/buildings/partially_finished/dismantlesite/init.lua'
--- data/tribes/buildings/partially_finished/dismantlesite/init.lua	2016-09-22 16:45:02 +0000
+++ data/tribes/buildings/partially_finished/dismantlesite/init.lua	2016-11-03 07:38:41 +0000
@@ -1,4 +1,6 @@
 -- RST
+-- .. _lua_tribes_buildings_dismantlesites:
+--
 -- Dismantle Sites
 -- ---------------
 --
@@ -14,30 +16,12 @@
 dirname = path.dirname(__file__)
 
 -- RST
--- .. function:: new_dismantlesite_type(table)
+-- .. 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.
+--                It only contains :ref:`lua_tribes_buildings_common`.
 --
 tribes:new_dismantlesite_type {
    msgctxt = "building",

=== modified file 'data/tribes/buildings/productionsites/atlanteans/armorsmithy/init.lua'
--- data/tribes/buildings/productionsites/atlanteans/armorsmithy/init.lua	2016-10-30 19:06:01 +0000
+++ data/tribes/buildings/productionsites/atlanteans/armorsmithy/init.lua	2016-11-03 07:38:41 +0000
@@ -1,4 +1,6 @@
 -- RST
+-- .. _lua_tribes_buildings_productionsites:
+--
 -- Production Sites
 -- ----------------
 --
@@ -15,58 +17,70 @@
 dirname = path.dirname(__file__)
 
 -- RST
--- .. function:: new_productionsite_type(table)
+-- .. 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.
+--                In addition to the :ref:`lua_tribes_buildings_common`, it contains the following entries:
+--
+--    **size**
+--        *Mandatory*. In addition to the common size values ``"small"``,
+--        ``"medium"``, or ``"big"``, production sites can also have size ``"mine"``
+--        for defining a mine building to be built on mountains.
+--
+--    **working_positions**
+--        *Mandatory*. The name and amount for each worker type working at this
+--        building, e.g.::
+--
+--            working_positions = { atlanteans_armorsmith = 1 },
+--
+--    **inputs**
+--        *Optional*. The name and amount for each ware input queue, e.g.::
+--
+--            inputs = {
+--                { name = "coal", amount = 10 },
+--                { name = "iron", amount = 8 },
+--                { name = "gold", amount = 8 }
+--            },
+--
+--    **outputs**
+--        *Optional*. The wares/workers produced by this building, e.g.::
+--
+--            outputs = { "shield_advanced", "shield_steel" },
+--
+--    **programs**.
+--        *Mandatory*. 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 :doc:`productionsite_program`.
+--
+--    **out_of_resource_notification**.
+--        *Optional*. This table defines the message sent by the productionsite
+--        to the player if it has run out of a resource to collect. There are 4
+--        entries:
+--
+--        **title**
+--            *Mandatory*. A concise message title for the list in the inbox.
+--
+--        **heading**
+--            *Mandatory*. A longer version of the title, shown in the message body.
+--
+--        **message**
+--            *Mandatory*. The actual message. Translation needs to be fetched with pgettext.
+--
+--        **productivity_threshold**
+--            *Optional. Default:* ``100``. An int value in percent to trigger the message.
+--
+--        Example::
+--
+--            out_of_resource_notification = {
+--                -- Translators: Short for "Out of ..." for a resource
+--                title = _"No Fields",
+--                heading = _"Out of Fields",
+--                message = pgettext("atlanteans_building", "The farmer working at this farm has no cleared soil to plant his seeds."),
+--                productivity_threshold = 30
+--            },
 --
 tribes:new_productionsite_type {
    msgctxt = "atlanteans_building",

=== modified file 'data/tribes/buildings/trainingsites/atlanteans/dungeon/init.lua'
--- data/tribes/buildings/trainingsites/atlanteans/dungeon/init.lua	2016-09-10 16:50:51 +0000
+++ data/tribes/buildings/trainingsites/atlanteans/dungeon/init.lua	2016-11-03 07:38:41 +0000
@@ -1,4 +1,6 @@
 -- RST
+-- .. _lua_tribes_buildings_trainingsites:
+--
 -- Training Sites
 -- --------------
 --
@@ -14,39 +16,66 @@
 dirname = path.dirname(__file__)
 
 -- RST
--- .. function:: new_trainingsite_type(table)
+-- .. 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
+--                It is a special type of production site, so it has all the entries that :ref:`lua_tribes_buildings_productionsites` can have, plus the following entries:
+--
+--    **soldier_capacity**
+--        *Mandatory*. An int describing how many soldiers this building can house.
+--
+--    **trainer_patience**
+--        *Mandatory*. An int describing how patient the trainer is.
+--        If trainer patience runs out, a soldier will be kicked out.
+--
+--    **soldier attack**
+--        *Optional*. A table describing what is needed to train a soldier in attack.
+--        It contains the following entries:
+--
+--        **min_level**
+--            *Mandatory*. The minimum attack level that a soldier needs before it
+--            can be trained in attack at this training site.
+--
+--        **max_level**
+--            *Mandatory*. The maximum level of attack that a soldier can be trained in.
+--
+--        **food**
+--            *Optional*. A table with the types of 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**
+--            *Optional*. A table with the list of weapons that are used for
+--            attack training at the various levels.
+--
+--        Example::
+--
+--            ["soldier attack"] = {
+--                min_level = 0,
+--                max_level = 3,
+--                food = {
+--                    {"smoked_fish", "smoked_meat"},
+--                    {"atlanteans_bread"}
+--                },
+--                weapons = {
+--                    "trident_long",
+--                    "trident_steel",
+--                    "trident_double",
+--                    "trident_heavy_double"
+--                }
+--            },
+--
+--    **soldier defense**
+--            *Optional*. Just like ``soldier attack``, but for defense training.
+--
+--    **soldier health**
+--            *Optional*. Just like ``soldier attack``, but for health training.
+--
+--    **soldier evade**
+--            *Optional*. Just like ``soldier attack``, but for evade training.
 --
 tribes:new_trainingsite_type {
    msgctxt = "atlanteans_building",

=== modified file 'data/tribes/buildings/warehouses/atlanteans/headquarters/init.lua'
--- data/tribes/buildings/warehouses/atlanteans/headquarters/init.lua	2016-09-22 16:45:02 +0000
+++ data/tribes/buildings/warehouses/atlanteans/headquarters/init.lua	2016-11-03 07:38:41 +0000
@@ -1,4 +1,6 @@
 -- RST
+-- .. _lua_tribes_buildings_warehouses:
+--
 -- Headquarters, Warehouses and Ports
 -- ----------------------------------
 --
@@ -17,43 +19,27 @@
 dirname = path.dirname(__file__)
 
 -- RST
--- .. function:: new_warehouse_type(table)
+-- .. 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.
---
+--                In addition to the :ref:`lua_tribes_buildings_common`, it contains the following entries:
+--
+--    **size**
+--        *Mandatory*. In addition to the common size values ``"small"``,
+--        ``"medium"``, or ``"big"``, warehouses can also have size ``"port"``
+--        for defining a port building.
+--
+--    **heal_per_second**
+--        *Mandatory*. The number of health points that a garrisoned soldier will heal each second.
+--
+--    **conquers**
+--        *Optional. Default:* ``0``. The conquer radius for this building.
+--
+--    **destructible**
+--        *Optional. Default:* ``true``. Set this to ``false`` for headquarters.
+
 tribes:new_warehouse_type {
    msgctxt = "atlanteans_building",
    name = "atlanteans_headquarters",

=== modified file 'data/tribes/immovables/ashes/init.lua'
--- data/tribes/immovables/ashes/init.lua	2016-09-26 11:37:54 +0000
+++ data/tribes/immovables/ashes/init.lua	2016-11-03 07:38:41 +0000
@@ -1,4 +1,6 @@
 -- RST
+-- .. _lua_tribes_immovables:
+--
 -- Tribe Immovables
 -- ----------------
 --

=== modified file 'data/tribes/scripting/help/global_helptexts.lua'
--- data/tribes/scripting/help/global_helptexts.lua	2016-09-01 15:23:25 +0000
+++ data/tribes/scripting/help/global_helptexts.lua	2016-11-03 07:38:41 +0000
@@ -3,6 +3,8 @@
 --  =======================================================
 
 -- RST
+-- .. _lua_tribes_global_helptexts.lua:
+--
 -- global_helptexts.lua
 -- --------------------
 --

=== modified file 'data/tribes/ships/atlanteans/init.lua'
--- data/tribes/ships/atlanteans/init.lua	2016-09-26 11:37:54 +0000
+++ data/tribes/ships/atlanteans/init.lua	2016-11-03 07:38:41 +0000
@@ -1,4 +1,6 @@
 -- RST
+-- .. _lua_tribes_ships:
+--
 -- Ships
 -- -----
 --

=== modified file 'data/tribes/wares/armor/init.lua'
--- data/tribes/wares/armor/init.lua	2016-09-22 16:45:48 +0000
+++ data/tribes/wares/armor/init.lua	2016-11-03 07:38:41 +0000
@@ -1,4 +1,6 @@
 -- RST
+-- .. _lua_tribes_wares:
+--
 -- Wares
 -- -----
 --

=== modified file 'doc/sphinx/extract_rst.py'
--- doc/sphinx/extract_rst.py	2016-09-22 16:45:48 +0000
+++ doc/sphinx/extract_rst.py	2016-11-03 07:38:41 +0000
@@ -36,17 +36,17 @@
     ('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'),
+     'militarysite', 'lua_tribes_buildings'),
     ('data/tribes/buildings/productionsites/atlanteans/armorsmithy',
-     'productionsite', 'lua_tribes_units'),
+     'productionsite', 'lua_tribes_buildings'),
     ('data/tribes/buildings/trainingsites/atlanteans/dungeon',
-     'trainingsite', 'lua_tribes_units'),
+     'trainingsite', 'lua_tribes_buildings'),
     ('data/tribes/buildings/warehouses/atlanteans/headquarters',
-     'warehouse', 'lua_tribes_units'),
+     'warehouse', 'lua_tribes_buildings'),
     ('data/tribes/buildings/partially_finished/constructionsite',
-     'constructionsite', 'lua_tribes_units'),
+     'constructionsite', 'lua_tribes_buildings'),
     ('data/tribes/buildings/partially_finished/dismantlesite',
-     'dismantlesite', 'lua_tribes_units'),
+     'dismantlesite', 'lua_tribes_buildings'),
      ('data/tribes/immovables/ashes',
      'immovables', 'lua_tribes_units'),
      ('data/tribes/ships/atlanteans',

=== added file 'doc/sphinx/source/animations.rst'
--- doc/sphinx/source/animations.rst	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/animations.rst	2016-11-03 07:38:41 +0000
@@ -0,0 +1,34 @@
+Animations
+==========
+
+Animations are defined as Lua tables. They look like this::
+
+   animations = {
+      idle = {
+         pictures = path.list_files(path.dirname(__file__) .. "idle_??.png"),
+         hotspot = { 5, 7 },
+         fps = 4,
+         sound_effect = {
+            directory = "sound/foo",
+            name = "bar",
+         },
+      },
+      working = ...
+   }
+
+Let's have a detailed look at the ``idle`` animation:
+
+idle
+   *Mandatory*. This is the name of the animation. It can be referenced by this name e.g. if you want to call it in a production program.
+
+pictures
+   *Mandatory*. A template for the image names. Our example will pick up any image from ``idle_00.png`` through ``idle_99.png`` in the specified directory path – the current path in our example. These images can optionally have corresponding player color mask images called ``idle_00_pc.png`` through ``idle_99_pc.png``.
+
+hotspot
+   *Mandatory*. The x, y coordinates for adjusting the placement of the animation. Increase ``x`` to shift the animation to the left and ``y`` to shift it upwards.
+
+fps
+   *Optional*. The frames per second for this animation if you want to deviate from the default fps. Do not specify this value if you have only 1 animation frame.
+
+sound_effect
+   *Optional*. Our example will look for the sound files ``bar_00.ogg`` through ``bar_99.ogg`` in the directory ``data/sound/foo`` and play them in sequence.

=== modified file 'doc/sphinx/source/lua_tribes.rst'
--- doc/sphinx/source/lua_tribes.rst	2016-09-01 18:32:58 +0000
+++ doc/sphinx/source/lua_tribes.rst	2016-11-03 07:38:41 +0000
@@ -1,3 +1,5 @@
+.. _lua_tribes:
+
 Scripts for Tribes
 ==================
 

=== added file 'doc/sphinx/source/lua_tribes_buildings.rst.org'
--- doc/sphinx/source/lua_tribes_buildings.rst.org	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/lua_tribes_buildings.rst.org	2016-11-03 07:38:41 +0000
@@ -0,0 +1,142 @@
+Buildings
+=========
+
+Buildings are defined in their ``init.lua`` file. They also have a corresponding ``helptexts.lua`` file that contains their help texts.
+
+Types of Buildings
+------------------
+
+Widelands knows about the following types of buildings:
+
+.. toctree::
+   :maxdepth: 3
+
+REPLACE_ME
+
+.. _lua_tribes_buildings_common:
+
+Common Building Properties
+--------------------------
+
+Buildings are defined with Lua functions called ``new_<building_type>_type{table}``. The contents of ``table`` depend on the type of building that you are defining. The common properties shared by all buildings are:
+
+
+**msgctxt**
+    *Mandatory*. The context that Gettext will use to disambiguate the translations for
+    strings in this table, e.g.::
+
+        msgctxt = "atlanteans_building",
+
+**name**
+    *Mandatory*. A string containing the internal name of this building, e.g.::
+
+        name = "atlanteans_fortress",
+
+**descname**
+    *Mandatory*. The translatable display name. Use ``pgettext`` with the ``msgctxt``
+    above to fetch the string, e.g.::
+
+        descname = pgettext("atlanteans_building", "Fortress"),
+
+**helptext_script**
+    *Mandatory*. The full path to the ``helptexts.lua`` script for this building.
+
+**icon**
+    *Mandatory*. The full path to the menu icon for this building.
+
+**size**
+    *Mandatory*. The size of this building: ``"small"``, ``"medium"``, or ``"big"``.
+
+**vision_range**
+    *Optional. Default:* ``0``. The size of the radius that the building sees.
+
+**buildcost**
+    *Optional*. A table with the wares used to build this building, containing
+    warename - amount pairs, e.g.::
+
+        buildcost = { log = 4, granite = 2 }
+
+    When ``buildcost`` is defined, you also need to define ``return_on_dismantle``.
+
+**return_on_dismantle**
+    *Optional*. The wares that this building will give back to the player when it is
+    dismantled, e.g.::
+
+        buildcost = { log = 2, granite = 1 }
+
+**enhancement**
+    *Optional*. The name of a building that this building can be enhanced to, e.g.::
+
+        enhancement = "atlanteans_fancy_building",
+
+    If ``enhancement`` is defined, the building that this building enhances
+    to will need to define ``enhancement_cost`` and
+    ``return_on_dismantle_on_enhanced``.
+
+**enhancement_cost**
+    *Optional*. The wares needed to upgrade this building, e.g.::
+
+        enhancement_cost = { log = 1, granite = 1 }
+
+**return_on_dismantle_on_enhanced**
+    *Optional*. 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**
+    *Mandatory*. A table containing all animations for this building. Every building
+    needs to have an ``idle`` animation. Other animations that a building
+    can have are ``build``, ``working``, ``unoccupied``. Mines also have
+    an ``unoccupied`` animation.
+    See :doc:`animations` for a detailed description of the animation format.
+
+**needs_seafaring**
+    *Optional. Default:* ``false``. Set to ``true`` if this building will only be available on seafaring maps.
+
+**aihints**
+    *Mandatory*. A list of name - value pairs with hints for the AI. Can be empty.
+
+
+Help Texts
+----------
+
+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 :ref:`lua_tribes_global_helptexts.lua`.
+
+
+.. 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 ``lua_tribes_global_helptexts.lua`` script.
+
+
+.. 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 :ref:`lua_tribes_global_helptexts.lua` script.
+
+   :returns: Localized lore text
+
+
+.. 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 :ref:`lua_tribes_global_helptexts.lua` script if you're not ready to define this yet.
+
+   :returns: Localized purpose text
+
+
+.. 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_performance()
+
+   Returns a localized string with a performance helptext for this building. You can use ``no_purpose_text_yet()`` from the :ref:`lua_tribes_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.

=== modified file 'doc/sphinx/source/lua_tribes_units.rst.org'
--- doc/sphinx/source/lua_tribes_units.rst.org	2016-09-01 18:32:58 +0000
+++ doc/sphinx/source/lua_tribes_units.rst.org	2016-11-03 07:38:41 +0000
@@ -15,4 +15,5 @@
 .. toctree::
    :maxdepth: 3
 
+   autogen_toc_lua_tribes_buildings
 REPLACE_ME

=== added file 'doc/sphinx/source/map_objects.rst'
--- doc/sphinx/source/map_objects.rst	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/map_objects.rst	2016-11-03 07:38:41 +0000
@@ -0,0 +1,9 @@
+World and Tribes
+================
+
+.. toctree::
+   :maxdepth: 3
+
+   animations
+   autogen_toc_lua_world
+   lua_tribes

=== modified file 'doc/sphinx/source/reference.rst'
--- doc/sphinx/source/reference.rst	2016-09-01 18:32:58 +0000
+++ doc/sphinx/source/reference.rst	2016-11-03 07:38:41 +0000
@@ -5,6 +5,5 @@
    :maxdepth: 3
 
    core
-   autogen_toc_lua_world
-   lua_tribes
+   map_objects
    autogen_toc_auxiliary

=== modified file 'src/logic/map_objects/immovable.cc'
--- src/logic/map_objects/immovable.cc	2016-11-03 07:20:57 +0000
+++ src/logic/map_objects/immovable.cc	2016-11-03 07:38:41 +0000
@@ -265,6 +265,9 @@
 
 /**
  * Parse a tribes immovable from its init file.
+ *
+ * The contents of 'table' are documented in
+ * /data/tribes/immovables/ashes/init.lua
  */
 ImmovableDescr::ImmovableDescr(const std::string& init_descname,
                                const LuaTable& table,

=== modified file 'src/logic/map_objects/tribes/building.cc'
--- src/logic/map_objects/tribes/building.cc	2016-11-03 07:20:57 +0000
+++ src/logic/map_objects/tribes/building.cc	2016-11-03 07:38:41 +0000
@@ -50,7 +50,9 @@
 namespace Widelands {
 
 static const int32_t BUILDING_LEAVE_INTERVAL = 1000;
-
+/**
+  * The contents of 'table' are documented in doc/sphinx/source/lua_tribes_buildings.rst.org
+  */
 BuildingDescr::BuildingDescr(const std::string& init_descname,
                              const MapObjectType init_type,
                              const LuaTable& table,

=== modified file 'src/logic/map_objects/tribes/constructionsite.cc'
--- src/logic/map_objects/tribes/constructionsite.cc	2016-11-03 07:20:57 +0000
+++ src/logic/map_objects/tribes/constructionsite.cc	2016-11-03 07:38:41 +0000
@@ -41,6 +41,10 @@
 
 namespace Widelands {
 
+/**
+  * The contents of 'table' are documented in
+  * /data/tribes/buildings/partially_finished/constructionsite/init.lua
+  */
 ConstructionSiteDescr::ConstructionSiteDescr(const std::string& init_descname,
                                              const LuaTable& table,
                                              const EditorGameBase& egbase)

=== modified file 'src/logic/map_objects/tribes/dismantlesite.cc'
--- src/logic/map_objects/tribes/dismantlesite.cc	2016-10-26 19:43:40 +0000
+++ src/logic/map_objects/tribes/dismantlesite.cc	2016-11-03 07:38:41 +0000
@@ -39,6 +39,11 @@
 
 namespace Widelands {
 
+/**
+  * The contents of 'table' are documented in
+  * /data/tribes/buildings/partially_finished/dismantlesite/init.lua
+  */
+
 DismantleSiteDescr::DismantleSiteDescr(const std::string& init_descname,
                                        const LuaTable& table,
                                        const EditorGameBase& egbase)

=== modified file 'src/logic/map_objects/tribes/militarysite.cc'
--- src/logic/map_objects/tribes/militarysite.cc	2016-08-04 15:49:05 +0000
+++ src/logic/map_objects/tribes/militarysite.cc	2016-11-03 07:38:41 +0000
@@ -43,6 +43,10 @@
 
 namespace Widelands {
 
+/**
+  * The contents of 'table' are documented in
+  * /data/tribes/buildings/militarysites/atlanteans/castle/init.lua
+  */
 MilitarySiteDescr::MilitarySiteDescr(const std::string& init_descname,
                                      const LuaTable& table,
                                      const EditorGameBase& egbase)

=== modified file 'src/logic/map_objects/tribes/productionsite.cc'
--- src/logic/map_objects/tribes/productionsite.cc	2016-09-02 11:48:37 +0000
+++ src/logic/map_objects/tribes/productionsite.cc	2016-11-03 07:38:41 +0000
@@ -53,6 +53,10 @@
 ==============================================================================
 */
 
+/**
+  * The contents of 'table' are documented in
+  * /data/tribes/buildings/productionsites/atlanteans/armorsmithy/init.lua
+  */
 ProductionSiteDescr::ProductionSiteDescr(const std::string& init_descname,
                                          const std::string& msgctxt,
                                          MapObjectType init_type,

=== modified file 'src/logic/map_objects/tribes/ship.cc'
--- src/logic/map_objects/tribes/ship.cc	2016-11-03 07:20:57 +0000
+++ src/logic/map_objects/tribes/ship.cc	2016-11-03 07:38:41 +0000
@@ -105,6 +105,10 @@
 
 }  // namespace
 
+/**
+ * The contents of 'table' are documented in
+ * /data/tribes/ships/atlanteans/init.lua
+ */
 ShipDescr::ShipDescr(const std::string& init_descname, const LuaTable& table)
    : BobDescr(init_descname, MapObjectType::SHIP, MapObjectDescr::OwnerType::kTribe, table) {
 

=== modified file 'src/logic/map_objects/tribes/trainingsite.cc'
--- src/logic/map_objects/tribes/trainingsite.cc	2016-08-04 15:49:05 +0000
+++ src/logic/map_objects/tribes/trainingsite.cc	2016-11-03 07:38:41 +0000
@@ -41,6 +41,10 @@
 
 const uint32_t TrainingSite::training_state_multiplier_ = 12;
 
+/**
+  * The contents of 'table' are documented in
+  * /data/tribes/buildings/trainingsites/atlanteans/dungeon/init.lua
+  */
 TrainingSiteDescr::TrainingSiteDescr(const std::string& init_descname,
                                      const LuaTable& table,
                                      const EditorGameBase& egbase)

=== modified file 'src/logic/map_objects/tribes/tribe_descr.cc'
--- src/logic/map_objects/tribes/tribe_descr.cc	2016-08-04 15:49:05 +0000
+++ src/logic/map_objects/tribes/tribe_descr.cc	2016-11-03 07:38:41 +0000
@@ -51,6 +51,10 @@
 
 namespace Widelands {
 
+/**
+  * The contents of 'table' are documented in
+  * /data/tribes/atlanteans.lua
+  */
 TribeDescr::TribeDescr(const LuaTable& table, const TribeBasicInfo& info, const Tribes& init_tribes)
    : name_(table.get_string("name")), descname_(info.descname), tribes_(init_tribes) {
 

=== modified file 'src/logic/map_objects/tribes/ware_descr.cc'
--- src/logic/map_objects/tribes/ware_descr.cc	2016-08-04 15:49:05 +0000
+++ src/logic/map_objects/tribes/ware_descr.cc	2016-11-03 07:38:41 +0000
@@ -31,6 +31,10 @@
 
 namespace Widelands {
 
+/**
+ * The contents of 'table' are documented in
+ * /data/tribes/wares/armor/init.lua
+ */
 WareDescr::WareDescr(const std::string& init_descname, const LuaTable& table)
    : MapObjectDescr(MapObjectType::WARE, table.get_string("name"), init_descname, table) {
 

=== modified file 'src/logic/map_objects/tribes/warehouse.cc'
--- src/logic/map_objects/tribes/warehouse.cc	2016-08-04 15:49:05 +0000
+++ src/logic/map_objects/tribes/warehouse.cc	2016-11-03 07:38:41 +0000
@@ -231,6 +231,10 @@
 ==============================
 */
 
+/**
+  * The contents of 'table' are documented in
+  * /data/tribes/buildings/warehouses/atlanteans/headquarters/init.lua
+  */
 WarehouseDescr::WarehouseDescr(const std::string& init_descname,
                                const LuaTable& table,
                                const EditorGameBase& egbase)

=== modified file 'src/scripting/lua_root.cc'
--- src/scripting/lua_root.cc	2016-09-27 06:30:47 +0000
+++ src/scripting/lua_root.cc	2016-11-03 07:38:41 +0000
@@ -518,8 +518,8 @@
 
 .. class:: Tribes
 
-   This offers access to the objects available for the tribes and allows to add
-   new objects.
+	This offers access to the objects available for the tribes and allows to add
+	new objects. See :ref:`lua_tribes` for detailed documentation.
 */
 
 const char LuaTribes::className[] = "Tribes";
@@ -568,12 +568,13 @@
  */
 
 /* RST
-   .. method:: new_constructionsite_type(table)
-
-      Adds a new constructionsite building type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_constructionsite_type{table}
+
+		Adds a new constructionsite building type. Takes a single argument, a table with
+		the descriptions. See :ref:`lua_tribes_buildings_constructionsites` for detailed
+		documentation.
+
+		:returns: :const:`0`
 */
 int LuaTribes::new_constructionsite_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -591,12 +592,13 @@
 }
 
 /* RST
-   .. method:: new_dismantlesite_type(table)
-
-      Adds a new disnamtlesite building type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_dismantlesite_type{table}
+
+		Adds a new disnamtlesite building type. Takes a single argument, a table with
+		the descriptions. See :ref:`lua_tribes_buildings_dismantlesites` for detailed
+		documentation.
+
+		:returns: :const:`0`
 */
 int LuaTribes::new_dismantlesite_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -614,12 +616,13 @@
 }
 
 /* RST
-   .. method:: new_militarysite_type(table)
-
-      Adds a new militarysite building type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_militarysite_type{table}
+
+		Adds a new militarysite building type. Takes a single argument, a table with
+		the descriptions. See :ref:`lua_tribes_buildings_militarysites` for detailed
+		documentation.
+
+		:returns: :const:`0`
 */
 int LuaTribes::new_militarysite_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -637,12 +640,13 @@
 }
 
 /* RST
-   .. method:: new_productionsite_type(table)
-
-      Adds a new productionsite building type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_productionsite_type{table}
+
+		Adds a new productionsite building type. Takes a single argument, a table with
+		the descriptions. See :ref:`lua_tribes_buildings_productionsites` for detailed
+		documentation.
+
+		:returns: :const:`0`
 */
 int LuaTribes::new_productionsite_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -660,12 +664,13 @@
 }
 
 /* RST
-   .. method:: new_trainingsite_type(table)
-
-      Adds a new trainingsite building type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_trainingsite_type{table}
+
+		Adds a new trainingsite building type. Takes a single argument, a table with
+		the descriptions. See :ref:`lua_tribes_buildings_trainingsites` for detailed
+		documentation.
+
+		:returns: :const:`0`
 */
 int LuaTribes::new_trainingsite_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -683,12 +688,13 @@
 }
 
 /* RST
-   .. method:: new_warehouse_type(table)
-
-      Adds a new warehouse building type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_warehouse_type{table}
+
+		Adds a new warehouse building type. Takes a single argument, a table with
+		the descriptions. See :ref:`lua_tribes_buildings_warehouses` for detailed
+		documentation.
+
+		:returns: :const:`0`
 */
 int LuaTribes::new_warehouse_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -706,12 +712,13 @@
 }
 
 /* RST
-   .. method:: new_immovable_type(table)
-
-      Adds a new immovable type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_immovable_type{table}
+
+		Adds a new immovable type. Takes a single argument, a table with
+		the descriptions. See :ref:`lua_tribes_immovables` for detailed
+		documentation.
+
+		:returns: :const:`0`
 */
 int LuaTribes::new_immovable_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -728,12 +735,13 @@
 }
 
 /* RST
-   .. method:: new_ship_type(table)
-
-      Adds a new ship type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_ship_type{table}
+
+		Adds a new ship type. Takes a single argument, a table with
+		the descriptions. See :ref:`lua_tribes_ships` for detailed
+		documentation.
+
+		:returns: :const:`0`
 */
 int LuaTribes::new_ship_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -750,12 +758,13 @@
 }
 
 /* RST
-   .. method:: new_ware_type(table)
-
-      Adds a new ware type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_ware_type{table}
+
+		Adds a new ware type. Takes a single argument, a table with
+		the descriptions. See :ref:`lua_tribes_wares` for detailed
+		documentation.
+
+		:returns: :const:`0`
 */
 int LuaTribes::new_ware_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -772,12 +781,12 @@
 }
 
 /* RST
-   .. method:: new_carrier_type(table)
-
-      Adds a new carrier worker type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_carrier_type{table}
+
+		Adds a new carrier worker type. Takes a single argument, a table with
+		the descriptions. See the files in tribes/ for usage examples.
+
+		:returns: :const:`nil`
 */
 int LuaTribes::new_carrier_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -795,12 +804,12 @@
 }
 
 /* RST
-   .. method:: new_soldier_type(table)
-
-      Adds a new soldier worker type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_soldier_type{table}
+
+		Adds a new soldier worker type. Takes a single argument, a table with
+		the descriptions. See the files in tribes/ for usage examples.
+
+		:returns: :const:`nil`
 */
 int LuaTribes::new_soldier_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -818,12 +827,12 @@
 }
 
 /* RST
-   .. method:: new_worker_type(table)
-
-      Adds a new worker type. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_worker_type{table}
+
+		Adds a new worker type. Takes a single argument, a table with
+		the descriptions. See the files in tribes/ for usage examples.
+
+		:returns: :const:`nil`
 */
 int LuaTribes::new_worker_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
@@ -841,12 +850,13 @@
 }
 
 /* RST
-   .. method:: new_tribe(table)
-
-      Adds a new tribe. Takes a single argument, a table with
-      the descriptions. See the files in tribes/ for usage examples.
-
-      :returns: :const:`nil`
+	.. method:: new_tribe{table}
+
+		Adds a new tribe. Takes a single argument, a table with
+		the descriptions. See :ref:`lua_tribes_<tribename>.lua` for detailed
+		documentation.
+
+		:returns: :const:`0`
 */
 int LuaTribes::new_tribe(lua_State* L) {
 	if (lua_gettop(L) != 2) {