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

[GunChleoc]

Added remaining Tribes units to Sphinx documentation (immovables, ships, wares).

[bunnybot (widelandsofficial)]

Continuous integration builds have changed state:

Travis build 1362. State: errored. Details: https://travis-ci.org/widelands/widelands/builds/162768596.
Appveyor build 1204. State: success. Details: https://ci.appveyor.com/project/widelands-dev/widelands/build/_widelands_dev_widelands_sphinx_tribes-1204.

[kaputtnik (franku)]

Extracts fine and sphinx-build found no failures.

I have just a question about the tabbing: If a table is used as parameter, the table entries are at the same column as the "Parameters" entry. Wouldn't it be better to have the "Table"-entries indented?

Example image: https://bugs.launchpad.net/widelands/+bug/1512093/+attachment/4748854/+files/sphinx_tabbed.png

review: Approve (testing)

[GunChleoc (gunchleoc)]

Let's continue this discussion in the bug.

@bunnybot merge

=== modified file 'data/tribes/buildings/militarysites/atlanteans/castle/init.lua'
--- data/tribes/buildings/militarysites/atlanteans/castle/init.lua	2016-09-02 09:30:13 +0000
+++ data/tribes/buildings/militarysites/atlanteans/castle/init.lua	2016-09-26 11:38:31 +0000
@@ -24,7 +24,7 @@
 --
 --    **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.
+--    **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.
 --

=== modified file 'data/tribes/buildings/partially_finished/constructionsite/init.lua'
--- data/tribes/buildings/partially_finished/constructionsite/init.lua	2016-09-02 08:27:34 +0000
+++ data/tribes/buildings/partially_finished/constructionsite/init.lua	2016-09-26 11:38:31 +0000
@@ -25,7 +25,7 @@
 --
 --    **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.
+--    **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.
 --

=== modified file 'data/tribes/buildings/partially_finished/dismantlesite/init.lua'
--- data/tribes/buildings/partially_finished/dismantlesite/init.lua	2016-09-02 08:27:34 +0000
+++ data/tribes/buildings/partially_finished/dismantlesite/init.lua	2016-09-26 11:38:31 +0000
@@ -25,7 +25,7 @@
 --
 --    **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.
+--    **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.
 --

=== modified file 'data/tribes/buildings/productionsites/atlanteans/armorsmithy/init.lua'
--- data/tribes/buildings/productionsites/atlanteans/armorsmithy/init.lua	2016-09-10 16:50:51 +0000
+++ data/tribes/buildings/productionsites/atlanteans/armorsmithy/init.lua	2016-09-26 11:38:31 +0000
@@ -26,7 +26,7 @@
 --
 --    **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.
+--    **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.
 --

=== modified file 'data/tribes/buildings/warehouses/atlanteans/headquarters/init.lua'
--- data/tribes/buildings/warehouses/atlanteans/headquarters/init.lua	2016-09-02 09:30:13 +0000
+++ data/tribes/buildings/warehouses/atlanteans/headquarters/init.lua	2016-09-26 11:38:31 +0000
@@ -28,7 +28,7 @@
 --
 --    **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.
+--    **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.
 --

=== modified file 'data/tribes/immovables/ashes/init.lua'
--- data/tribes/immovables/ashes/init.lua	2015-11-03 18:18:27 +0000
+++ data/tribes/immovables/ashes/init.lua	2016-09-26 11:38:31 +0000
@@ -1,5 +1,36 @@
+-- RST
+-- Tribe Immovables
+-- ----------------
+--
+-- Immovables are entities not connected to a road that a tribe can own,
+-- for example a corn field or a ship under construction.
+--
+-- Tribe Immovables are defined in
+-- ``data/tribes/immovables/<immovable_name>/init.lua``.
+
 dirname = path.dirname(__file__)
 
+-- RST
+-- .. function:: new_immovable_type(table)
+--
+--    This function adds the definition of a tribe immovable to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will
+--                add to this immovable. 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 immovable.
+--
+--    **descname**: The translatable display name. Use ``pgettext`` with the
+--    ``msgctxt`` above to fetch the string.
+--
+--    **programs**: A table with the programs that this immovable will perform,
+--    e.g. ``{ animate=idle 4500,  remove= }``
+--
+--    **animations**: A table containing all animations for this immovable.
+--
 tribes:new_immovable_type {
    msgctxt = "immovable",
    name = "ashes",

=== modified file 'data/tribes/ships/atlanteans/init.lua'
--- data/tribes/ships/atlanteans/init.lua	2015-11-03 18:18:27 +0000
+++ data/tribes/ships/atlanteans/init.lua	2016-09-26 11:38:31 +0000
@@ -1,3 +1,13 @@
+-- RST
+-- Ships
+-- -----
+--
+-- Each tribe can have one ship that is used to explore the seas and transport
+-- wares between ports.
+--
+-- Ships are defined in
+-- ``data/tribes/ships/<tribe_name>/init.lua``.
+
 dirname = path.dirname(__file__)
 
 animations = {
@@ -14,6 +24,29 @@
 }
 add_worker_animations(animations, "sail", dirname, "sail", {89, 86}, 10)
 
+
+-- RST
+-- .. function:: new_ship_type(table)
+--
+--    This function adds the definition of a ship to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will
+--                add to this ship. 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 ship.
+--
+--    **descname**: The translatable display name. Use ``pgettext`` with the
+--    ``msgctxt`` above to fetch the string.
+--
+--    **capacity**: An int defining how many wares or workers this ship can transport
+--
+--    **vision_range**: How far the ship can see.
+--
+--    **animations**: A table containing all animations for this ship.
+--    Ships have an "idle", a "sinking" and a directional "sail" animation.
 tribes:new_ship_type {
    name = "atlanteans_ship",
    -- TRANSLATORS: This is the ship's name used in lists of units

=== modified file 'data/tribes/wares/armor/init.lua'
--- data/tribes/wares/armor/init.lua	2015-12-11 16:54:00 +0000
+++ data/tribes/wares/armor/init.lua	2016-09-26 11:38:31 +0000
@@ -1,5 +1,46 @@
+-- RST
+-- Wares
+-- -----
+--
+-- Wares are used to build buildings, produce other wares and recruit units.
+--
+-- Wares are defined in
+-- ``data/tribes/wares/<ware_name>/init.lua``.
+-- The ware will also need its help texts, which are defined in
+-- ``data/tribes/wares/<ware_name>/helptexts.lua``
+
+
 dirname = path.dirname(__file__)
 
+-- RST
+-- .. function:: new_ware_type(table)
+--
+--    This function adds the definition of a ware to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add
+--                to this ware. 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 ware.
+--
+--    **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 ware.
+--
+--    **icon**: The full path to the menu icon for this ware.
+--
+--    **default_target_quantity**: A table listing the default target quantity
+--    for each tribe's economy. For example, ``{ atlanteans = 3, empire = 1 }``
+--
+--    **preciousness**: How precious this ware is to each tribe. For example,
+--    ``{ atlanteans = 0, empire = 1 }``
+--
+--    **animations**: A table containing all animations for this ware.
+--    Wares have an "idle" animation.
+
 tribes:new_ware_type {
    msgctxt = "ware",
    name = "armor",

=== modified file 'doc/sphinx/extract_rst.py'
--- doc/sphinx/extract_rst.py	2016-09-02 09:48:28 +0000
+++ doc/sphinx/extract_rst.py	2016-09-26 11:38:31 +0000
@@ -47,6 +47,12 @@
      'constructionsite', 'lua_tribes_units'),
     ('data/tribes/buildings/partially_finished/dismantlesite',
      'dismantlesite', 'lua_tribes_units'),
+     ('data/tribes/immovables/ashes',
+     'immovables', 'lua_tribes_units'),
+     ('data/tribes/ships/atlanteans',
+     'ships', 'lua_tribes_units'),
+     ('data/tribes/wares/armor',
+     'wares', 'lua_tribes_units'),
 )