Autogen script links, table of contents, and demo!

Automatically generating the link target for each script saves a lot of
time and potential for errors.

Each kind-of-script page now includes a link target for that page, and
also a table of contents.

In-script markers to delimit text for Sphinx extraction now use native
docstring markers from Ruby, which is a lot more elegant in .rb scripts
- and robust, as long as the fisrt docstring is valid .rst!

adaptation.rb

@@ -1,5 +1,14 @@
 # View or set level of cavern adaptation for the selected unit or the whole fort
 # based on removebadthoughts.rb
+=begin
+
+adaptation
+==========
+View or set level of cavern adaptation for the selected unit or the whole fort.
+Usage: ``adaptation <show|set> <him|all> [value]``.  The ``value`` must be
+between 0 and 800,000 inclusive.
+
+=end
 
 # Color constants, values mapped to color_value enum in include/ColorText.h
 COLOR_GREEN  = 2

add-thought.lua

@@ -1,18 +1,14 @@
 -- Adds emotions to creatures.
 --@ module = true
 
---[[
-BEGIN_DOCS
-
-.. _add-thought:
+--[[=begin
 
 add-thought
 ===========
 Adds a thought or emotion to the selected unit.  Can be used by other scripts,
 or the gui invoked by running ``add-thought gui`` with a unit selected.
 
-END_DOCS
-]]
+=end]]
 
 local utils=require('utils')
 

armoks-blessing.lua

@@ -3,7 +3,16 @@
 -- arguments allow for skills to be adjusted as well
 -- WARNING: USING THIS SCRIPT WILL ADJUST ALL DWARVES IN PLAY!
 -- by vjek
+--[[=begin
 
+armoks-blessing
+===============
+Runs the equivalent of `rejuvenate`, `elevate-physical`, `elevate-mental`, and
+`brainwash` on all dwarves currently on the map.  This is an extreme change,
+which sets every stat to an ideal - legendary skills, great traits, and
+easy-to-satisfy preferences.
+
+=end]]
 function rejuvenate(unit)
     if unit==nil then
         print ("No unit available!  Aborting with extreme prejudice.")

autofarm.rb

@@ -1,3 +1,19 @@
+
+=begin
+
+autofarm
+========
+Automatically handle crop selection in farm plots based on current plant stocks.
+Selects a crop for planting if current stock is below a threshold.
+Selected crops are dispatched on all farmplots.
+
+Usage::
+
+    autofarm start
+    autofarm default 30
+    autofarm threshold 150 helmet_plump tail_pig
+
+=end
 class AutoFarm
 
     def initialize

autolabor-artisans.lua

@@ -1,5 +1,12 @@
 -- Executes an autolabor command for each labor where skill level influences output quality.
 
+--[[=begin
+
+autolabor-artisans
+==================
+Runs `autolabor`, with settings tuned for small but highly skilled workforces.
+
+=end]]
 local artisan_labors = {
     "CARPENTER",
     "DETAIL",

autounsuspend.rb

@@ -1,4 +1,12 @@
 # un-suspend construction jobs, on a recurring basis
+=begin
+
+autounsuspend
+=============
+Automatically unsuspend jobs in workshops, on a recurring basis.
+See `unsuspend` for one-off use, or `resume` ``all``.
+
+=end
 
 class AutoUnsuspend
     attr_accessor :running