Included gomill framework for SGF and GTP support, and sketched out SGF game-loading code.

gomill/docs/intro.rst

@@ -0,0 +1,97 @@
+Introduction
+============
+
+Gomill is a suite of tools, and a Python library, for use in developing and
+testing Go-playing programs. It is based around the Go Text Protocol
+(:term:`GTP`) and the Smart Game Format (:term:`SGF`).
+
+The principal tool is the :dfn:`ringmaster`, which plays programs against each
+other and keeps track of the results.
+
+Ringmaster features include:
+
+- testing multiple pairings in one run
+- playing multiple games in parallel
+- displaying live results
+- engine configuration by command line options or |gtp| commands
+- a protocol for including per-move engine diagnostics in |sgf| output
+- automatically tuning engine parameters based on game results
+  (**experimental**)
+
+.. contents:: Page contents
+   :local:
+   :backlinks: none
+
+
+Ringmaster example
+------------------
+
+Create a file called :file:`demo.ctl`, with the following contents::
+
+  competition_type = 'playoff'
+
+  board_size = 9
+  komi = 7.5
+
+  players = {
+      'gnugo-l1' : Player('gnugo --mode=gtp --level=1'),
+      'gnugo-l2' : Player('gnugo --mode=gtp --level=2'),
+      }
+
+  matchups = [
+      Matchup('gnugo-l1', 'gnugo-l2',
+              alternating=True,
+              number_of_games=5),
+      ]
+
+(If you don't have :program:`gnugo` installed, change the
+:setting-cls:`Player` definitions to use a command line for whatever |gtp|
+engine you have available.)
+
+Then run ::
+
+  $ ringmaster demo.ctl
+
+The ringmaster will run five games between the two players, showing a summary
+of the results on screen, and then exit.
+
+(If the ringmaster is not already installed, see :doc:`install` for
+instructions.)
+
+The final display should be something like this::
+
+  gnugo-l1 v gnugo-l2 (5/5 games)
+  board size: 9   komi: 7.5
+             wins              black        white      avg cpu
+  gnugo-l1      2 40.00%       1 33.33%     1 50.00%      1.05
+  gnugo-l2      3 60.00%       1 50.00%     2 66.67%      1.12
+                               2 40.00%     3 60.00%
+
+  = Results =
+  game 0_0: gnugo-l2 beat gnugo-l1 W+21.5
+  game 0_1: gnugo-l2 beat gnugo-l1 B+9.5
+  game 0_2: gnugo-l2 beat gnugo-l1 W+14.5
+  game 0_3: gnugo-l1 beat gnugo-l2 W+7.5
+  game 0_4: gnugo-l1 beat gnugo-l2 B+2.5
+
+The ringmaster will create several files named like :file:`demo.{xxx}` in the
+same directory as :file:`demo.ctl`, including a :file:`demo.sgf` directory
+containing game records.
+
+
+The Python library
+------------------
+
+Gomill also provides a Python library for working with |gtp| and |sgf|, though
+as of Gomill |version| only part of the API is stable. See :doc:`library` for
+details.
+
+
+The example scripts
+-------------------
+
+Some :doc:`example scripts <example_scripts>` are also included in the Gomill
+distribution, as illustrations of the library interface and in some cases as
+tools useful in themselves.
+
+