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!

docs/Contributing.rst

@@ -128,9 +128,29 @@ there are a few important standards for completeness and consistent style.  Trea
 this section as a guide rather than iron law, match the surrounding text, and you'll
 be fine.
 
-Every script, plugin, or command should be documented.  This is an active project,
-and the best place to put this documentation might change.  For now, it's usually
-either ``docs/Scripts.rst`` or ``docs/Plugins.rst``.
+Everything should be documented!  For plugins, it's a work in progress - use
+``docs/Plugins.rst`` for now.  Core functions and general explanations should
+go in the documents for that component; if it's not clear add a new section
+as some may be missing.
+
+Scripts can use a custom autodoc function, based on the Sphinx ``include``
+directive and Ruby docstring conventions - any lines between ``=begin`` and
+``=end`` are copied into the appropriate scripts documentation page.
+They **must** have a heading which exactly matches the command, underlined
+with ``=====`` to the same length.  For example, a lua file would have::
+
+    --[[=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]]
+
+Ruby scripts use the same syntax, but obviously omit the leading ``--[[`` and
+trailing ``]]`` which denote a multiline comment in lua.
+``=begin`` and ``=end`` are native syntax (and matched in lua for convenience).
 
 Where the heading for a section is also the name of a command, the spelling
 and case should exactly match the command to enter in the DFHack command line.
@@ -141,7 +161,7 @@ Sphinx (our documentation system) will make sure paragraphs flow.
 If there aren't many options or examples to show, they can go in a paragraph of
 text.  Use double-backticks to put commands in monospaced font, like this::
 
-    You can use ``cleanall scattered x`` to dump tattered or abandoned items.
+    You can use ``cleanowned scattered x`` to dump tattered or abandoned items.
 
 If the command takes more than three arguments, format the list as a table
 called Options.  The table *only* lists arguments, not full commands.
@@ -174,6 +194,8 @@ section like this::
     =========
 
 Add link targets if you need them, but otherwise plain headings are preferred.
+Scripts using the in-source docs option, which should be all of them, have
+link targets created automatically.
 
 Other ways to help
 ==================

docs/Scripts.rst

@@ -15,12 +15,37 @@ or from the init file.
 only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt
 the next instruction.
 
-Here's the contents page for this document:
 
-.. contents::
+The following pages document all the standard DFHack scripts.
 
+* Basic scripts are not stored in any subdirectory, and can be invoked directly.
+  They are generally useful tools for any player.
+* ``devel/*`` scripts are intended for developers, or still substantially unfinished.
+  If you don't already know what they do, best to leave them alone.
+* ``fix/*`` scripts fix various bugs and issues, some of them obscure.
+* ``gui/*`` scripts implement dialogs in the main game window.
+
+  In order to avoid user confusion, as a matter of policy all these tools
+  display the word "DFHack" on the screen somewhere while active.
+  When that is not appropriate because they merely add keybinding hints to
+  existing DF screens, they deliberately use red instead of green for the key.
+
+* ``modtools/*`` scripts provide tools for modders, often with changes
+  to the raw files, and are not intended to be called manually by end-users.
+
+  These scripts are mostly useful for raw modders and scripters. They all have
+  standard arguments: arguments are of the form ``tool -argName1 argVal1
+  -argName2 argVal2``. This is equivalent to ``tool -argName2 argVal2 -argName1
+  argVal1``. It is not necessary to provide a value to an argument name: ``tool
+  -argName3`` is fine. Supplying the same argument name multiple times will
+  result in an error. Argument names are preceded with a dash. The ``-help``
+  argument will print a descriptive usage string describing the nature of the
+  arguments. For multiple word argument values, brackets must be used: ``tool
+  -argName4 [ sadf1 sadf2 sadf3 ]``. In order to allow passing literal braces as
+  part of the argument, backslashes are used: ``tool -argName4 [ \] asdf \foo ]``
+  sets ``argName4`` to ``\] asdf foo``. The ``*-trigger`` scripts have a similar
+  policy with backslashes.
 
-The following pages document all the standard DFHack scripts.
 
 .. toctree::
    :glob:
@@ -44,16 +69,8 @@ The following pages document all the standard DFHack scripts.
    /scripts/3rdparty/*/*
 
 
-=======
-devel/*
-=======
-Scripts in this subdirectory are intended for developers, or still substantially
-under development.  If you don't already know what they do, best to leave them alone.
 
-================================================
-fix/* - scripts that fix bugs or common problems
-================================================
-Scripts in this subdirectory fix various bugs and issues, some of them obscure.
+
 
 fix/blood-del
 =============
@@ -112,20 +129,6 @@ fix/stuckdoors
 Fix doors that are stuck open due to incorrect map occupancy flags, eg due to
 incorrect use of teleport.
 
-========================================
-gui/* - scripts with an ingame interface
-========================================
-Scripts that implement dialogs inserted into the main game window are put in this
-directory.
-
-.. note::
-
-    In order to avoid user confusion, as a matter of policy all these tools
-    display the word "DFHack" on the screen somewhere while active.
-
-    When that is not appropriate because they merely add keybinding hints to
-    existing DF screens, they deliberately use red instead of green for the key.
-
 
 .. _gui/advfort:
 
@@ -503,27 +506,6 @@ material is matched against the barrel itself. Then, if you select, say, iron,
 and then try to change the input item type, now it won't let you select *plant*;
 you have to unset the material first.
 
-.. _modtools:
-
-========================
-modtools/* - for modders
-========================
-Scripts which provide tools for modders, often with changes to the raw files.
-Not intended to be called manually by end-users.
-
-These scripts are mostly useful for raw modders and scripters. They all have
-standard arguments: arguments are of the form ``tool -argName1 argVal1
--argName2 argVal2``. This is equivalent to ``tool -argName2 argVal2 -argName1
-argVal1``. It is not necessary to provide a value to an argument name: ``tool
--argName3`` is fine. Supplying the same argument name multiple times will
-result in an error. Argument names are preceded with a dash. The ``-help``
-argument will print a descriptive usage string describing the nature of the
-arguments. For multiple word argument values, brackets must be used: ``tool
--argName4 [ sadf1 sadf2 sadf3 ]``. In order to allow passing literal braces as
-part of the argument, backslashes are used: ``tool -argName4 [ \] asdf \foo ]``
-sets ``argName4`` to ``\] asdf foo``. The ``*-trigger`` scripts have a similar
-policy with backslashes.
-
 .. _modtools/add-syndrome:
 
 modtools/add-syndrome
@@ -641,53 +623,6 @@ Transforms a unit into another unit type, possibly permanently.
 =============
 Other Scripts
 =============
-These scripts are not stored in any subdirectory, and can be invoked directly.
-
-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.
-
-.. _adaptation:
-
-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.
-
-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.
-Use in moderation; it's as 'cheaty' as DFHack gets.
-
-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
-
-.. _autolabor-artisans:
-
-autolabor-artisans
-==================
-Runs `autolabor`, with settings tuned for small but highly skilled workforces.
-
-.. _autounsuspend:
-
-autounsuspend
-=============
-Automatically unsuspend jobs in workshops, on a recurring basis.
-See `unsuspend` for one-off use, or `resume` ``all``.
 
 ban-cooking
 ===========

docs/conf.py

@@ -58,11 +58,13 @@ def document_scripts():
             kinds['base'].append(s)
         else:
             kinds.get(k_fname[0], []).append(s)
-    template = ('.. include:: /{}\n   :start-after: BEGIN_DOCS\n'
-                '   :end-before: END_DOCS')
+    template = ('.. _{}:\n\n'
+                '.. include:: /{}\n'
+                '   :start-after: =begin\n'
+                '   :end-before: =end\n')
     for key, value in kinds.items():
-        kinds[key] = [
-            template.format(x[1]) for x in sorted(value, key=lambda x: x[0])]
+        kinds[key] = [template.format(x[0], x[1])
+                      for x in sorted(value, key=lambda x: x[0])]
     # Finally, we write our _auto/* files for each kind of script
     if not os.path.isdir('_auto'):
         os.mkdir('_auto')
@@ -73,7 +75,8 @@ def document_scripts():
         'gui': 'GUI Scripts',
         'modtools': 'Scripts for Modders'}
     for k in head:
-        title = '{l}\n{t}\n{l}\n\n'.format(t=head[k], l=len(head[k])*'#')
+        title = '.. _{k}:\n\n{l}\n{t}\n{l}\n\n.. contents::\n\n'.format(
+            k=k, t=head[k], l=len(head[k])*'#')
         mode = 'w' if sys.version_info.major > 2 else 'wb'
         with open('_auto/{}.rst'.format(k), mode) as outfile:
             outfile.write(title)

scripts/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

scripts/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')
 

scripts/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.")

scripts/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

scripts/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",

scripts/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