Merge lp:~widelands-dev/widelands/document_worker_program into lp:widelands

[GunChleoc]

Added documentation for worker programs.

This documentation is to replace https://wl.widelands.org/wiki/WorkerCommands/, which was never finished.

Also hooked the production program reference into the TOC.

The changes in implementation.rst are just fixed line endings, plus a code highlighting command at the top of the file.

[bunnybot (widelandsofficial)]

Continuous integration builds have changed state:

Travis build 2599. State: passed. Details: https://travis-ci.org/widelands/widelands/builds/268974597.
Appveyor build 2421. State: success. Details: https://ci.appveyor.com/project/widelands-dev/widelands/build/_widelands_dev_widelands_document_worker_program-2421.

[kaputtnik (franku)]

For code examples there should be either a highlight directive used or the code-block directive. So comments are shown properly and some keywords in the comments (e.g.: and, or) are shown correctly.

See: http://build-me-the-docs-please.readthedocs.io/en/latest/Using_Sphinx/ShowingCodeExamplesInSphinx.html

If we are using only code examples in language lua, we could define the config var 'highlight_language'. See:

https://www.sphinx-doc.org/en/stable/config.html#confval-highlight_language

This has to be set in doc/sphinx/source/conf.py

One inline comment :-)

[kaputtnik (franku)]

Forgot to save the inline comment...

[GunChleoc (gunchleoc)]

Thanks!

[GunChleoc (gunchleoc)]

This is ready now.

review: Needs Resubmitting

[kaputtnik (franku)]

Did not read completely, just stumbled over 'Common Worker Properties':

I think this part is explained vice versa as other parts...

"Workers are defined with Lua functions called new_worker_type{table}. The contents of table depend on the type of worker that you are defining. The common properties shared by all workers are:"

Shouldn't be the function name (new_worker_type{table}) a header? So backlinks to this make more sense, imho. E.g. in the worker Programs:

"Worker programs are defined in the programs subtable specified in calls to tribes:new_worker_type. Each worker program..."

Currently the link to tribes:new_worker_type points to "Common Worker Properties" and one has to read the text to find the functions name.

Formatting looks good so far (testing with local website) :-)

[GunChleoc (gunchleoc)]

Sphinx won't link to :any:`tribes:new_worker_type{table}`, so I cheated a bit and added the function header but kept the link to the section header.

[bunnybot (widelandsofficial)]

Continuous integration builds have changed state:

Travis build 2604. State: passed. Details: https://travis-ci.org/widelands/widelands/builds/269322779.
Appveyor build 2426. State: success. Details: https://ci.appveyor.com/project/widelands-dev/widelands/build/_widelands_dev_widelands_document_worker_program-2426.

[kaputtnik (franku)]

Regarding the types of workers

https://wl.widelands.org/docs/wl/autogen_toc_lua_tribes_workers/#types-of-workers

it should be added that the common worker properties do also apply to these special workers. Something like:

"In addition to the basic worker type, see below, Widelands knows about the following sub types, which should have also the Common Worker Properties:"

Can't find the right wording here :-S

Two comments, otherwise looks good to me.

Clashing of developer and user :-D

[kaputtnik (franku)]

Sidenote: Just found http://localhost:8000/docs/wl/productionsite_program/

Is there a reason why this is not inside the lua scripting? http://localhost:8000/docs/wl/lua_index/

[GunChleoc (gunchleoc)]

> it should be added that the common worker properties do also apply to these special workers.

That's already documented in the subclasses themselves, like this:

"This table contains all the data that the game engine will add to this carrier. It contains the Common Worker Properties, plus the following additional property:"

https://wl.widelands.org/docs/wl/autogen_carriers_lua_tribes_workers_init/

> Clashing of developer and user :-D

The documentation is for the user, so your feedback is invaluable :)

[kaputtnik (franku)]

Looks good :-)

> > it should be added that the common worker properties do also apply to these
> special workers.
>
> That's already documented in the subclasses themselves, like this:
>
> "This table contains all the data that the game engine will add to this
> carrier. It contains the Common Worker Properties, plus the following
> additional property:"

I read this and this is fine. The problem (for me) is that the function definition of new_worker_type{table} is part of "Common Worker Properties". So a user reads the text of new_carrier(), clicks back to "Common Worker Properties" and is prompted with the function of new_worker_type{}.

From my point of view it would be much logical to have 'new_worker_type{}' in section "Types of Workers"

https://wl.widelands.org/docs/wl/autogen_toc_lua_tribes_workers/#types-of-workers

and add a sentence like: "All types of workers have the same Common worker Properties"

Backlinks to "Common Worker Properties" are the not that confusing then.

[GunChleoc (gunchleoc)]

I think I have found a solution now. I have added a subpage for the basic worker type.

Regarding the productionsite programs, I haven't touched them at all yet, because that would make the diff too big.

[kaputtnik (franku)]

That's perfect :-)

Maybe the sentence shown with each worker type regarding the helptext could then be omitted in each worker-type-page and placed in the 'Workers' section.

"Each type of worker will also need its help texts, which are defined in data/tribes/wares/<tribe name>/soldier/helptexts.lua"

And linking to http://localhost:8000/docs/wl/autogen_toc_lua_tribes_workers/#help-texts ?

Feel free to merge... Otherwise i get caught up in the details ;)

[GunChleoc (gunchleoc)]

Good idea about the link. I have kept the phrasing though.

Thanks for the review :)

@bunnybot merge

=== modified file 'data/tribes/workers/atlanteans/armorsmith/init.lua'
--- data/tribes/workers/atlanteans/armorsmith/init.lua	2017-02-20 13:53:01 +0000
+++ data/tribes/workers/atlanteans/armorsmith/init.lua	2017-08-30 16:47:36 +0000
@@ -1,5 +1,18 @@
 -- The basic worker documentation is located in /doc/sphinx/lua_tribes_workers_rst.org
 
+-- RST
+-- .. _lua_tribes_basic_workers:
+--
+-- Workers
+-- --------
+--
+-- Workers of this basic type work in buildings. Their function is defined either
+-- through the :ref:`buildings' programs <productionsite_programs>`, or through their :ref:`own programs <tribes_worker_programs>`.
+--
+-- Workers are defined in
+-- ``data/tribes/workers/<tribe name>/<worker_name>/init.lua``.
+-- The worker will also need its :ref:`help texts <lua_tribes_workers_helptexts>`,
+-- which are defined in ``data/tribes/wares/<tribe name>/<worker_name>/helptexts.lua``.
 dirname = path.dirname(__file__)
 
 animations = {
@@ -11,7 +24,14 @@
 add_walking_animations(animations, "walk", dirname, "walk", {8, 23}, 10)
 add_walking_animations(animations, "walkload", dirname, "walkload", {8, 23}, 10)
 
-
+-- RST
+-- .. function:: new_worker_type{table}
+--
+--    This function adds the definition of a worker to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add
+--                to this worker. It contains the properties in
+--                :ref:`lua_tribes_workers_common`.
 tribes:new_worker_type {
    msgctxt = "atlanteans_worker",
    name = "atlanteans_armorsmith",

=== modified file 'data/tribes/workers/atlanteans/carrier/init.lua'
--- data/tribes/workers/atlanteans/carrier/init.lua	2017-04-21 23:04:00 +0000
+++ data/tribes/workers/atlanteans/carrier/init.lua	2017-08-30 16:47:36 +0000
@@ -10,8 +10,8 @@
 --
 -- Carriers, like workers, are defined in
 -- ``data/tribes/workers/<tribe name>/<worker_name>/init.lua``.
--- The carrier will also need its help texts, which are defined in
--- ``data/tribes/wares/<tribe name>/<worker_name>/helptexts.lua``
+-- The carrier will also need its :ref:`help texts <lua_tribes_workers_helptexts>`,
+-- which are defined in ``data/tribes/wares/<tribe name>/<worker_name>/helptexts.lua``
 
 dirname = path.dirname(__file__)
 
@@ -26,7 +26,7 @@
 add_walking_animations(animations, "walkload", dirname, "walkload", {8, 25}, 10)
 
 -- RST
--- .. function:: new_carrier_type(table)
+-- .. function:: new_carrier_type{table}
 --
 --    This function adds the definition of a carrier to the engine.
 --

=== modified file 'data/tribes/workers/atlanteans/soldier/init.lua'
--- data/tribes/workers/atlanteans/soldier/init.lua	2017-02-20 13:53:01 +0000
+++ data/tribes/workers/atlanteans/soldier/init.lua	2017-08-30 16:47:36 +0000
@@ -9,8 +9,8 @@
 --
 -- Soldiers, like workers, are defined in
 -- ``data/tribes/workers/<tribe name>/soldier/init.lua``.
--- The soldier will also need its help texts, which are defined in
--- ``data/tribes/wares/<tribe name>/soldier/helptexts.lua``
+-- The soldier will also need its :ref:`help texts <lua_tribes_workers_helptexts>`,
+-- which are defined in ``data/tribes/wares/<tribe name>/soldier/helptexts.lua``
 
 dirname = path.dirname(__file__)
 
@@ -74,7 +74,7 @@
 add_walking_animations(animations, "walk", dirname, "walk", {20, 34}, 10)
 
 -- RST
--- .. function:: new_soldier_type(table)
+-- .. function:: new_soldier_type{table}
 --
 --    This function adds the definition of a soldier to the engine.
 --

=== modified file 'doc/sphinx/extract_rst.py'
--- doc/sphinx/extract_rst.py	2017-02-20 13:53:01 +0000
+++ doc/sphinx/extract_rst.py	2017-08-30 16:47:36 +0000
@@ -20,6 +20,7 @@
     ('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/logic/map_objects/tribes/worker_program.cc', 'autogen_tribes_worker_programs.rst'),
 )
 
 # These directories are scanned without knowing which file
@@ -53,6 +54,8 @@
      'ships', 'lua_tribes_units'),
      ('data/tribes/wares/armor',
      'wares', 'lua_tribes_units'),
+     ('data/tribes/workers/atlanteans/armorsmith',
+     'basic_workers', 'lua_tribes_workers'),
      ('data/tribes/workers/atlanteans/carrier',
      'carriers', 'lua_tribes_workers'),
      ('data/tribes/workers/atlanteans/soldier',

=== modified file 'doc/sphinx/source/animations.rst'
--- doc/sphinx/source/animations.rst	2017-08-27 08:21:51 +0000
+++ doc/sphinx/source/animations.rst	2017-08-30 16:47:36 +0000
@@ -122,7 +122,7 @@
    **walkload**
       *Optional*. A directional animation. The worker is walking while carrying something.
 
-Any further animations like e.g. "plant", "harvest", or "breed" will be referenced in the ``programs table``, under the ``animation`` command.
+Any further animations like e.g. "plant", "harvest", or "breed" will be referenced in the :ref:`tribes_worker_programs`, under the ``animation`` command.
 
 For example, a fisher could look like this::
 

=== modified file 'doc/sphinx/source/conf.py'
--- doc/sphinx/source/conf.py	2017-07-04 19:17:39 +0000
+++ doc/sphinx/source/conf.py	2017-08-30 16:47:36 +0000
@@ -86,6 +86,8 @@
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+highlight_language = 'lua'
+
 
 # -- Options for HTML output ---------------------------------------------------
 

=== modified file 'doc/sphinx/source/implementation.rst'
--- doc/sphinx/source/implementation.rst	2013-10-19 10:42:47 +0000
+++ doc/sphinx/source/implementation.rst	2017-08-30 16:47:36 +0000
@@ -1,11 +1,13 @@
+.. highlight:: default
+
 Implementation Notes
 ====================
 
 This section is for developers who want to add more features to the Lua
 support in widelands (or that want to track down bugs). This contains notes
-about how certain things are implemented and how to add to it. 
+about how certain things are implemented and how to add to it.
 
-.. Note:: 
+.. Note::
 
    This section is not for scenario designers, only for developers
    working directly on widelands.
@@ -17,7 +19,7 @@
 The scripting interface is defined in ``scripting/scripting.h``. It consists
 of the two classes LuaInterface for running scripts and LuaCouroutine which
 wraps a Lua coroutine. The Lua interface is accessed via the lua() function in
-Editor_Game_Base. 
+Editor_Game_Base.
 
 There are two game commands for lua: ``Cmd_LuaScript`` and
 ``Cmd_LuaCoroutine``. The first one is only used to enqueue the initial
@@ -58,7 +60,7 @@
 
    const char L_Player::className[] = "Player"; // Name of this class
    const MethodType<L_Player> L_Player::Methods[] = {
-      METHOD(L_Player, __eq),  // compare operator 
+      METHOD(L_Player, __eq),  // compare operator
       METHOD(L_Player, place_flag), // a method called place_flag
       {0, 0}, // end of methods table
    };
@@ -85,18 +87,18 @@
 Luna Classes need even more boilerplate to work correctly. Firstly, they must
 define a function ``get_modulename`` that returns a ``const char *`` which
 will be the submodule name where this class is registered. For our example,
-Player would return ``"game"`` because it is defined in ``wl.game``. 
+Player would return ``"game"`` because it is defined in ``wl.game``.
 
 The class must also define two constructors, one that takes no arguments and
 is only used to create a empty class that is created for unpersisting. And a
 second one that takes a ``lua_State *`` that is called when the construction
 is requested from Lua, that is if ``wl.game.Player()`` is called. Some (most?)
 classes can't be constructed from Lua and should then answer with
-``report_error()``. 
+``report_error()``.
 
 En plus, a function ``__persist(lua_State *)`` and a function
 ``__unpersist(lua_State *)`` must be defined. They are discussed in the next
-section. 
+section.
 
 .. _Luna: http://lua-users.org/wiki/SimplerCppBinding
 
@@ -104,10 +106,10 @@
 -----------
 
 When a savegame is created, the current environment of Lua is persisted. For
-this, I used a library called Eris_.  
+this, I used a library called Eris_.
 
 .. _Eris: https://github.com/fnuecke
- 
+
 The global environment is persisted into the file map/globals.dump. Everything
 is persisted except of the Lua build-in functions and everything in the ``wl``
 table and some of our own global functions. Those are c-functions that can not
@@ -115,7 +117,7 @@
 everything in the auxiliary scripts are saved to disk, so save games only
 depend on the API defined inside the Widelands.
 
-Coroutines are persisted in their ``Cmd_LuaCoroutine`` package. 
+Coroutines are persisted in their ``Cmd_LuaCoroutine`` package.
 
 Luna classes have to implement two functions to be properly persistable:
 
@@ -139,20 +141,20 @@
 *)`` to the Map_Map_Object_Loader and ``get_mos(lua_State *)`` to the
 Map_Map_Object_Saver. These function return 0 when not called in
 ``__persist`` and ``__unpersist``.
-		
+
 Testing
 -------
 
 Lua support is currently tested in two different scenarios. Both life in
 ``src/scripting/test`` and they work essentially the same: they are normal
-scenarios which contain a Lua unittest framework named lunit_ that the 
+scenarios which contain a Lua unittest framework named lunit_ that the
 author agreed to be used in widelands like that. The scripts than use various
-Lua functions and check that they do the expected things. 
+Lua functions and check that they do the expected things.
 
 If you add new features to the Lua support of Widelands, consider also adding
 tests in the appropriate places in the test suite. This guarantees that nothing
 unexpected happens in scenarios and it will show the most common bugs quite
-easily. 
+easily.
 
 .. _lunit: http://www.nessie.de/mroth/lunit/
 
@@ -173,7 +175,7 @@
    #### Test Suite finished.
 
    353 Assertions checked. All Tests passed!
-   
+
 If the test suite fails, widelands will be kept running and the error message
 of the failed test will be visible in the output. This is then a bug and
 should be reported.
@@ -185,7 +187,7 @@
 between different versions. First, you need to run it as scenario::
 
    $ ./widelands --scenario=src/scripting/test/persistence.wmf
-       
+
 This will result in the creation of various Lua objects. Widelands will then
 immediately safe the game as ``lua_persistence.wgf`` and exit. You can then
 load this game::

=== modified file 'doc/sphinx/source/lua_tribes_workers.rst.org'
--- doc/sphinx/source/lua_tribes_workers.rst.org	2017-07-03 10:16:59 +0000
+++ doc/sphinx/source/lua_tribes_workers.rst.org	2017-08-30 16:47:36 +0000
@@ -1,16 +1,9 @@
-.. _workers:
-
 Workers
 =======
 
-Workers are defined in their ``init.lua`` file. They also have a corresponding
-``helptexts.lua`` file that contains their help text.
-Worker files are placed in ``data/tribes/workers/<tribe_name>/<worker_name>/``.
-
-Types of Workers
-----------------
-
-In addition to the basic worker type, Widelands knows about the following sub types:
+Workers are created in a warehouse or recruited by a building. Most workers will work in buildings, while special worker types will act as carriers or soldiers.
+
+Widelands knows about the following worker types:
 
 .. toctree::
    :maxdepth: 3
@@ -19,11 +12,10 @@
 
 .. _lua_tribes_workers_common:
 
-
 Common Worker Properties
 ------------------------
 
-Workers are defined with Lua functions called ``new_worker_type{table}``. The contents of ``table`` depend on the type of worker that you are defining. The common properties shared by all workers are:
+Workers are defined with Lua functions called ``new_<worker_type>_type{table}``. The contents of ``table`` depend on the type of worker that you are defining. The common properties shared by all workers are:
 
   **msgctxt**: The context that Gettext will use to disambiguate the
   translations for strings in this table.
@@ -69,12 +61,11 @@
        worker programs. The "idle" and "walk" animations are mandatory.
 
   **programs**:
-      *Optional*. If the worker leaves the building to do his work, the worker
-      programs that define which type of space or resource the worker has to find
+      *Optional*. If the worker leaves the building to do his work, the :ref:`tribes_worker_programs` that define which type of space or resource the worker has to find
       on the map in order to do his work, and what that work is, including any
       animations and sounds played.
 
-TODO(GunChleoc): create Worker Program Reference
+.. _lua_tribes_workers_helptexts:
 
 Help Texts
 ----------

=== added file 'doc/sphinx/source/map_object_programs.rst'
--- doc/sphinx/source/map_object_programs.rst	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/map_object_programs.rst	2017-08-30 16:47:36 +0000
@@ -0,0 +1,14 @@
+Programs
+========
+
+Some map object will have special programs that define their behavior.
+You can describe these programs in their ``init.lua`` files, in the ``programs``
+table. Map objects that can have programs are:
+
+.. toctree::
+   :maxdepth: 3
+
+   Production Sites <productionsite_program>
+   Workers <autogen_tribes_worker_programs>
+
+The programs for Immovables haven't been documented yet.

=== modified file 'doc/sphinx/source/map_objects.rst'
--- doc/sphinx/source/map_objects.rst	2016-10-14 07:02:10 +0000
+++ doc/sphinx/source/map_objects.rst	2017-08-30 16:47:36 +0000
@@ -7,3 +7,4 @@
    animations
    autogen_toc_lua_world
    lua_tribes
+   map_object_programs

=== modified file 'doc/sphinx/source/productionsite_program.rst'
--- doc/sphinx/source/productionsite_program.rst	2017-08-27 08:21:51 +0000
+++ doc/sphinx/source/productionsite_program.rst	2017-08-30 16:47:36 +0000
@@ -76,6 +76,7 @@
 
 The different command types and the parameters that they take are explained below.
 
+.. highlight:: default
 
 Command Types
 ^^^^^^^^^^^^^

=== modified file 'src/logic/map_objects/tribes/worker_program.cc'
--- src/logic/map_objects/tribes/worker_program.cc	2017-01-25 18:55:59 +0000
+++ src/logic/map_objects/tribes/worker_program.cc	2017-08-30 16:47:36 +0000
@@ -30,6 +30,54 @@
 #include "sound/sound_handler.h"
 
 namespace Widelands {
+/* RST
+.. _tribes_worker_programs:
+
+Worker Programs
+===============
+
+Worker programs are defined in the ``programs`` subtable specified in the worker's :ref:`lua_tribes_workers_common`.
+Each worker program is a Lua table in itself and defined as a series of command strings.
+Commands can also have parameters, which are separated from each other by a blank space.
+These parameters can also have values, which are separated from the parameter name by a colon (:). Finally, programs can call other programs.
+The table looks like this::
+
+   programs = {
+      program_name1 = {
+         "program_name2",
+         "program_name3",
+      }
+      program_name2 = {
+         "command1 parameter1:value1 parameter2:value2",
+         "command2 parameter1",
+      },
+      program_name3 = {
+         "command3",
+         "command4 parameter1 parameter2 parameter3",
+      }
+   },
+
+The available commands are:
+
+- `createware`_
+- `mine`_
+- `breed`_
+- `setbobdescription`_
+- `findobject`_
+- `findspace`_
+- `walk`_
+- `animation`_
+- `return`_
+- `object`_
+- `plant`_
+- `create_bob`_
+- `object remove`_
+- `geologist`_
+- `geologist_find`_
+- `scout`_
+- `play_sound`_
+- `construct`_
+*/
 
 const WorkerProgram::ParseMap WorkerProgram::parsemap_[] = {
    {"mine", &WorkerProgram::parse_mine},
@@ -93,11 +141,27 @@
 	}
 }
 
+/* RST
+createware
+^^^^^^^^^^
+.. function:: createware \<ware_name\>
+
+   :arg string ware_name: The ware type to create, e.g. ``wheat``.
+
+   The worker will create and carry a ware of the given type. Example::
+
+      harvest = {
+         "findobject attrib:ripe_wheat radius:2",
+         "walk object",
+         "play_sound sound/farm scythe 220",
+         "animation harvesting 10000",
+         "object harvest",
+         "animation gathering 4000",
+         "createware wheat", -- Create 1 wheat and start carrying it
+         "return"
+      },
+*/
 /**
- * createware \<waretype\>
- *
- * The worker will create and carry a ware of the given type.
- *
  * iparam1 = ware index
  */
 void WorkerProgram::parse_createware(Worker::Action* act, const std::vector<std::string>& cmd) {
@@ -108,12 +172,30 @@
 	act->iparam1 = tribes_.safe_ware_index(cmd[1]);
 }
 
+/* RST
+mine
+^^^^
+.. function:: mine \<resource_name\> \<area\>
+
+   :arg string resource_name: The map resource to mine, e.g. ``fish``.
+
+   :arg int area: The radius that is scanned for decreasing the map resource, e.g. ``1``.
+
+   Mine on the current coordinates that the worker has walked to for resources decrease.
+   Example::
+
+      fish = {
+         "findspace size:any radius:7 resource:fish",
+         "walk coords",
+         "play_sound sound/fisher fisher_throw_net 192",
+         "mine fish 1", -- Remove a fish in an area of 1
+         "animation fishing 3000",
+         "play_sound sound/fisher fisher_pull_net 192",
+         "createware fish",
+         "return"
+      },
+*/
 /**
- * mine \<resource\> \<area\>
- *
- * Mine on the current coordinates (from walk or so) for resources decrease,
- * go home
- *
  * iparam1 = area
  * sparam1 = resource
  */
@@ -130,12 +212,27 @@
 		throw wexception("Bad area '%s'", cmd[2].c_str());
 }
 
+/* RST
+breed
+^^^^^
+.. function:: breed \<resource_name\> \<area\>
+
+   :arg string resource_name: The map resource to breed, e.g. ``fish``.
+
+   :arg int area: The radius that is scanned for increasing the map resource, e.g. ``1``.
+
+   Breed a resource on the current coordinates that the worker has walked to for
+   resources increase. Example::
+
+      breed = {
+         "findspace size:any radius:7 breed resource:fish",
+         "walk coords",
+         "animation freeing 3000",
+         "breed fish 1", -- Add a fish in an area of 1
+         "return"
+      },
+*/
 /**
- * breed \<resource\> \<area\>
- *
- * Breed on the current coordinates (from walk or so) for resource increase,
- * go home
- *
  * iparam1 = area
  * sparam1 = resource
  */
@@ -152,12 +249,28 @@
 		throw wexception("Bad area '%s'", cmd[2].c_str());
 }
 
+/* RST
+setbobdescription
+^^^^^^^^^^^^^^^^^
+.. function:: setbobdescription \<bob_name\> [\<bob_name\> ...]
+
+   :arg string bob_name: The bob type to add to the selection. Specify as many bob
+      types as you want.
+
+   Randomly select a bob name that can be used in subsequent commands,
+   e.g. create_bob. Used for releasing animals. Example::
+
+      release = {
+         "setbobdescription wildboar stag sheep", -- A wildboar, stag or sheep will be selected
+         "findspace size:any radius:3",
+         "walk coords",
+         "animation releasein 2000",
+         "create_bob",
+         "animation releaseout 2000",
+         "return"
+      },
+*/
 /**
- * setbobdescription \<bob name\> \<bob name\> ...
- *
- * Randomly select a bob name that can be used in subsequent commands
- * (e.g. create_bob).
- *
  * sparamv = possible bobs
  */
 void WorkerProgram::parse_setbobdescription(Worker::Action* act,
@@ -171,22 +284,39 @@
 		act->sparamv.push_back(cmd[i]);
 }
 
+/* RST
+findobject
+^^^^^^^^^^
+.. function:: findobject radius:\<distance\> [type:\<map_object_type\>] [attrib:\<attribute\>]
+
+   :arg int radius: Search for an object within the given radius around the worker.
+   :arg string type: The type of map object to search for. Defaults to ``immovable``.
+   :arg string attrib: The attribute that the map object should possess.
+
+   Find and select an object based on a number of predicates, which can be specified
+   in arbitrary order. The object can then be used in other commands like ``walk``
+   or ``object``. Examples::
+
+      cut_granite = {
+         "findobject attrib:rocks radius:6", -- Find rocks on the map within a radius of 6 from your building
+         "walk object", -- Now walk to those rocks
+         "play_sound sound/atlanteans/cutting stonecutter 192",
+         "animation hacking 12000",
+         "object shrink",
+         "createware granite",
+         "return"
+      },
+
+      hunt = {
+         "findobject type:bob radius:13 attrib:eatable", -- Find an eatable bob (animal) within a radius of 13 from your building
+         "walk object", -- Walk to where the animal is
+         "animation idle 1500",
+         "object remove",
+         "createware meat",
+         "return"
+      },
+*/
 /**
- * findobject key:value key:value ...
- *
- * Find and select an object based on a number of predicates.
- * The object can be used in other commands like walk or object.
- *
- * Predicates:
- * radius:\<dist\>
- * Find objects within the given radius
- *
- * attrib:\<attribute\>  (optional)
- * Find objects with the given attribute
- *
- * type:\<what\>         (optional, defaults to immovable)
- * Find only objects of this type
- *
  * iparam1 = radius predicate
  * iparam2 = attribute predicate (if >= 0)
  * sparam1 = type
@@ -226,36 +356,68 @@
 	workarea_info_[act->iparam1].insert(" findobject");
 }
 
+/* RST
+findspace
+^^^^^^^^^
+.. function:: findspace size:\<plot\> radius:\<distance\> [breed] [resource:\<name\>] [avoid:\<immovable_attribute\>] [space]
+
+   :arg string size: The size or building plot type of the free space.
+      The possible values are:
+
+      * ``any``: Any size will do.
+      * ``build``: Any building plot.
+      * ``small``: Small building plots only.
+      * ``medium``: Medium building plots only.
+      * ``big``: Big building plots only.
+      * ``mine``: Mining plots only.
+      * ``port``: Port spaces only.
+
+   :arg int radius: Search for map fields within the given radius around the worker.
+
+   :arg empty breed: Used in front of ``resource`` only: Also accept fields where the
+      resource has been depleted. Use this when looking for a place for breeding.
+
+   :arg string resource: A resource to search for. This is mainly intended for
+      fishers and suchlike, for non-detectable resources and default resources.
+
+   :arg string avoid: A field containing an immovable that has this attribute will
+      not be used.
+
+   :arg empty space: Find only fields that are walkable in such a way that all
+      neighbors are also walkable (an exception is made if one of the neighboring
+      fields is owned by this worker's location).
+
+   Find a map field based on a number of predicates.
+   The field can then be used in other commands like ``walk``. Examples::
+
+      breed = {
+         "findspace size:any radius:7 breed resource:fish", -- Find any field that can have fish in it for adding a fish to it below
+         "walk coords",
+         "animation freeing 3000",
+         "breed fish 1",
+         "return"
+      },
+
+      plant = {
+         "findspace size:any radius:5 avoid:field", -- Don't get in the way of the farmer's crops when planting trees
+         "walk coords",
+         "animation dig 2000",
+         "animation planting 1000",
+         "plant attrib:tree_sapling",
+         "animation water 2000",
+         "return"
+      },
+
+      plant = {
+         "findspace size:any radius:2 space", -- The farmer will want to walk to this field again later for harvesting his crop
+         "walk coords",
+         "animation planting 4000",
+         "plant tribe:field_tiny",
+         "animation planting 4000",
+         "return",
+      },
+*/
 /**
- * findspace key:value key:value ...
- *
- * Find a field based on a number of predicates.
- * The field can later be used in other commands, e.g. walk.
- *
- * Predicates:
- * radius:\<dist\>
- * Search for fields within the given radius around the worker.
- *
- * size:[any|build|small|medium|big|mine|port]
- * Search for fields with the given amount of space.
- *
- * breed
- * in resource:\<resname\>, also accept fields where the resource has been
- * depleted. Use this when looking for a place for breeding. Should be used
- * before resource:\<resname\>
- *
- * resource:\<resname\>
- * Resource to search for. This is mainly intended for fisher and
- * therelike (non detectable Resources and default resources)
- *
- * avoid:\<immovable attribute>
- * a field containing an immovable with that immovable should not be used
- *
- * space
- * Find only fields that are walkable such that all neighbours
- * are also walkable (an exception is made if one of the neighbouring
- * fields is owned by this worker's location).
- *
  * iparam1 = radius
  * iparam2 = FindNodeSize::sizeXXX
  * iparam3 = whether the "space" flag is set
@@ -325,15 +487,50 @@
 	workarea_info_[act->iparam1].insert(" findspace");
 }
 
+/* RST
+walk
+^^^^
+.. function:: walk \<destination_type\>
+
+   :arg string destination_type: Defines where to walk to. Possible destinations are:
+
+      * ``object``: Walk to a previously found and selected object.
+      * ``coords``: Walk to a previously found and selected field/coordinate.
+      * ``object-or-coords``: Walk to a previously found and selected object if present;
+        otherwise to previously found and selected field/coordinate.
+
+   Walk to a previously selected destination. Examples::
+
+      plant = {
+         "findspace size:any radius:2",
+         "walk coords", -- Walk to the space found by the command above
+         "animation planting 4000",
+         "plant tribe:blackrootfield_tiny",
+         "animation planting 4000",
+         "return"
+      },
+
+      harvest = {
+         "findobject attrib:ripe_blackroot radius:2",
+         "walk object", -- Walk to the blackroot field found by the command above
+         "animation harvesting 10000",
+         "object harvest",
+         "animation gathering 2000",
+         "createware blackroot",
+         "return"
+      },
+
+      buildship = {
+         "walk object-or-coords", -- Walk to coordinates from 1. or to object from 2.
+         "plant tribe:barbarians_shipconstruction unless object", -- 2. This will create an object for us if we don't have one yet
+         "play_sound sound/sawmill sawmill 230",
+         "animation work 500",
+         "construct", -- 1. This will find a space for us if no object has been planted yet
+         "animation work 5000",
+         "return"
+      },
+*/
 /**
- * walk \<where\>
- *
- * Walk to a previously selected destination. where can be one of:
- * object  walk to a previously found and selected object
- * coords  walk to a previously found and selected field/coordinate
- * object-or-coords  walk to a previously found and selected object if
- *         present; otherwise to previously found and selected coordinate
- *
  * iparam1 = walkXXX
  */
 void WorkerProgram::parse_walk(Worker::Action* act, const std::vector<std::string>& cmd) {
@@ -352,14 +549,28 @@
 		throw wexception("Bad walk destination '%s'", cmd[1].c_str());
 }
 
+/* RST
+animation
+^^^^^^^^^
+.. function:: animation \<name\> \<duration\>
+
+   :arg string name: The name of the animation.
+   :arg int duration: The time in milliseconds for which the animation will be played.
+
+   Play the given animation for the given duration. Example::
+
+      plantvine = {
+         "findspace size:any radius:1",
+         "walk coords",
+         "animation dig 2000", -- Play a digging animation for 2 seconds.
+         "plant tribe:grapevine_tiny",
+         "animation planting 3000", -- Play a planting animation for 3 seconds.
+         "return"
+      },
+*/
 /**
- * animation \<name\> \<duration\>
- *
- * Play the given animation for the given amount of time.
- *
  * iparam1 = anim id
  * iparam2 = duration
- *
  */
 void WorkerProgram::parse_animation(Worker::Action* act, const std::vector<std::string>& cmd) {
 	char* endp;
@@ -383,9 +594,19 @@
 		throw GameDataError("animation duration must be positive");
 }
 
+/* RST
+return
+^^^^^^
+.. function:: return
+
+   Return home and then drop any ware we're carrying onto our building's flag. Example::
+
+      scout = {
+         "scout 15 75000",
+         "return" -- Go home
+      }
+*/
 /**
- * Return home, drop an ware we're carrying onto our building's flag.
- *
  * iparam1 = 0: don't drop ware on flag, 1: do drop ware on flag
  */
 void WorkerProgram::parse_return(Worker::Action* act, const std::vector<std::string>&) {
@@ -393,11 +614,28 @@
 	act->iparam1 = 1;  // drop a ware on our owner's flag
 }
 
+/* RST
+object
+^^^^^^
+.. function:: object \<program_name\>
+
+   :arg string program_name: The name of the program to be executed.
+
+   Cause the currently selected object to execute its given program. Example::
+
+      chop = {
+         "findobject attrib:tree radius:10",
+         "walk object",
+         "play_sound sound/woodcutting fast_woodcutting 250",
+         "animation hacking 10000",
+         "play_sound sound/woodcutting tree-falling 130",
+         "object fall", -- Cause the tree to fall
+         "animation idle 2000",
+         "createware log",
+         "return"
+      }
+*/
 /**
- * object \<command\>
- *
- * Cause the currently selected object to execute the given program.
- *
  * sparam1 = object command name
  */
 void WorkerProgram::parse_object(Worker::Action* act, const std::vector<std::string>& cmd) {
@@ -408,12 +646,53 @@
 	act->sparam1 = cmd[1];
 }
 
+/* RST
+plant
+^^^^^
+.. function:: plant \<immmovable_type\> [\<immovable_type\> ...] [unless object]
+
+   :arg string immovable_type: The immovable to be planted. This can be specified
+      in two different ways:
+
+      * ``attrib:<attribute>``: Select at random any immovable that has this attribute.
+      * ``tribe:<immovable_name>``: Name a specific immovable to be planted.
+
+   :arg empty unless object: Do not plant the immovable if it already exists at
+      the current position.
+
+   Plant one of the given immovables on the current position, taking into account
+   the fertility of the area. Examples::
+
+      plant = {
+         "findspace size:any radius:5 avoid:field",
+         "walk coords",
+         "animation dig 2000",
+         "animation planting 1000",
+         "plant attrib:tree_sapling", -- Plant any random sapling tree
+         "animation water 2000",
+         "return"
+      },
+
+      plant = {
+         "findspace size:any radius:2 space",
+         "walk coords",
+         "animation planting 4000",
+         "plant tribe:field_tiny", -- Plant the tiny field immovable that the worker's tribe knows about
+         "animation planting 4000",
+         "return",
+      },
+
+      buildship = {
+         "walk object-or-coords",
+         "plant tribe:empire_shipconstruction unless object", -- Only create a shipconstruction if we don't already have one
+         "play_sound sound/sawmill sawmill 230",
+         "animation work 500",
+         "construct",
+         "animation work 5000",
+         "return"
+      }
+*/
 /**
- * plant \<immmovable type\> \<immovable type\> ... [unless object]
- *
- * Plant one of the given immovables on the current position taking into
- * account the fertility of the area.
- *
  * sparamv  list of object names
  * iparam1  one of plantXXX
  */
@@ -456,27 +735,66 @@
 	}
 }
 
-/**
- * Plants a bob (critter usually, maybe also worker later on). The immovable
- * type must have been selected by a previous command (i.e. setbobdescription).
- */
+/* RST
+create_bob
+^^^^^^^^^^
+.. function:: create_bob
+
+   Adds a bob (usually an animal) to the map at the worker's current location.
+   The list of possible bobs must have been selected by a previous command. Example::
+
+      release = {
+         "setbobdescription wildboar stag sheep", -- We want to release a wildboar, stag or sheep into the wild
+         "findspace size:any radius:3",
+         "walk coords",
+         "animation releasein 2000",
+         "create_bob", -- Now release a wildboar, stag or sheep into the wild
+         "animation releaseout 2000",
+         "return"
+      }
+*/
 void WorkerProgram::parse_create_bob(Worker::Action* act, const std::vector<std::string>&) {
 	act->function = &Worker::run_create_bob;
 }
 
-/**
- * Simply remove the currently selected object - make no fuss about it.
- */
+/* RST
+object remove
+^^^^^^^^^^^^^
+.. function:: object remove
+
+   Remove the currently selected object. Example::
+
+      hunt = {
+         "findobject type:bob radius:13 attrib:eatable", -- Select an object to remove
+         "walk object",
+         "animation idle 1000",
+         "object remove", -- The selected eatable map object has been hunted, so remove it from the map
+         "createware meat",
+         "return"
+      }
+*/
 void WorkerProgram::parse_removeobject(Worker::Action* act, const std::vector<std::string>&) {
 	act->function = &Worker::run_removeobject;
 }
 
+/* RST
+geologist
+^^^^^^^^^
+.. function:: geologist \<repetitions\> \<radius\> \<program_name\>
+
+   :arg int repetitions: The number of times that the geologist will move to a
+      different spot on the map to execute ``program_name``.
+
+   :arg int radius: The radius of map fields for the geologist not to stray from.
+
+   Walk around the starting point randomly within a certain radius, and execute
+   your ``program_name`` for some of the fields. Example::
+
+      expedition = {
+         "geologist 15 5 search"
+      },
+*/
 /**
- * geologist \<repeat #\> \<radius\> \<subcommand\>
- *
- * Walk around the starting point randomly within a certain radius,
- * and execute the subcommand for some of the fields.
- *
  * iparam1 = maximum repeat #
  * iparam2 = radius
  * sparam1 = subcommand
@@ -500,10 +818,22 @@
 	act->sparam1 = cmd[3];
 }
 
-/**
- * Check resources at the current position, and plant a marker object
- * when possible.
- */
+/* RST
+geologist_find
+^^^^^^^^^^^^^^
+.. function:: geologist_find
+
+   Check the current position for map resources (e.g. coal or water), and plant
+   a marker object when possible. Example::
+
+      search = {
+         "animation hacking 5000",
+         "animation idle 2000",
+         "play_sound sound/hammering geologist_hammer 192",
+         "animation hacking 3000",
+         "geologist_find" -- Plant a resource marker at the current location, according to what has been found.
+      }
+*/
 void WorkerProgram::parse_geologist_find(Worker::Action* act, const std::vector<std::string>& cmd) {
 	if (cmd.size() != 1)
 		throw wexception("Usage: geologist_find");
@@ -511,11 +841,23 @@
 	act->function = &Worker::run_geologist_find;
 }
 
+/* RST
+scout
+^^^^^
+.. function:: scout \<radius\> \<time\>
+
+   :arg int radius: The radius of map fields for the scout to explore.
+
+   :arg int time: The time in milliseconds that the scout will spend scouting.
+
+   Sends a scout out to run around scouting the area. Example::
+
+      scout = {
+         "scout 15 75000", -- Scout within a radius of 15 for 75 seconds
+         "return"
+      },
+*/
 /**
- * scout \<radius\> \<time\>
- *
- * Sends the scout out to run around scouting the area
- *
  * iparam1 = radius
  * iparam2 = time
  */
@@ -528,6 +870,32 @@
 	act->function = &Worker::run_scout;
 }
 
+/* RST
+play_sound
+^^^^^^^^^^
+.. function:: play_sound \<sound_dir\> \<sound_name\> [priority]
+
+   :arg string sound_dir: The directory (folder) that the sound files are in,
+      relative to the data directory.
+   :arg string sound_name: The name of the particular sound to play.
+      There can be multiple sound files to select from at random, e.g.
+      for `scythe`, we can have `scythe_00.ogg`, `scythe_01.ogg` ...
+
+   :arg int priority: The priority to give this sound. Maximum priority is 255.
+
+   Play a sound effect. Example::
+
+      harvest = {
+         "findobject attrib:ripe_wheat radius:2",
+         "walk object",
+         "play_sound sound/farm scythe 220", -- Almost certainly play a swishy harvesting sound
+         "animation harvesting 10000",
+         "object harvest",
+         "animation gathering 4000",
+         "createware wheat",
+         "return"
+      }
+*/
 void WorkerProgram::parse_play_sound(Worker::Action* act, const std::vector<std::string>& cmd) {
 	if (cmd.size() < 3 || cmd.size() > 4)
 		throw wexception("Usage: play_sound <sound_dir> <sound_name> [priority]");
@@ -541,6 +909,24 @@
 	                  atoi(cmd[3].c_str());
 }
 
+/* RST
+construct
+^^^^^^^^^
+.. function:: construct
+
+   Give the ware currently held by the worker to the immovable object for construction.
+   This is used in ship building. Example::
+
+      buildship = {
+         "walk object-or-coords", -- Walk to coordinates from 1. or to object from 2.
+         "plant tribe:barbarians_shipconstruction unless object", -- 2. This will create an object for us if we don't have one yet
+         "play_sound sound/sawmill sawmill 230",
+         "animation work 500",
+         "construct", -- 1. Add the current ware to the shipconstruction. This will find a space for us if no shipconstruction object has been planted yet
+         "animation work 5000",
+         "return"
+      },
+*/
 /**
  * construct
  *