Use Sphinx to replace wiki

1 files changed, 129 insertions, 0 deletions

diff --git a/docs/source/config.rst b/docs/source/config.rst
new file mode 100644
index 0000000..d3aed3f
--- /dev/null
+++ b/docs/source/config.rst
@@ -0,0 +1,129 @@
+Configuration
+=============
+
+Configuration Files
+-------------------
+
+At the time of writing, this is the default configuration file:
+
+.. code-block:: ini
+
+   [Graphics]
+   Screen width: 640
+   Screen height: 480
+   # FPS should not be greater than refresh rate.
+   Maximum FPS: 60
+
+   [Sound]
+   Muted: no
+   # Volume must be between 0.0 and 1.0.
+   Music volume: 1.0
+   # Use space music background, which sounds cold and creepy.
+   Space theme: no
+
+   [Control]
+   # Touch-friendly control
+   Touch: no
+   # Input values should be either from Mouse1 to Mouse3 or a keyboard key
+   # and they are case-insensitively read.
+   # Aliases for special keys are listed here (without the K_ part):
+   # http://www.pygame.org/docs/ref/key.html
+   # Key combinations are not supported.
+   New game: F2
+   Toggle pause: p
+   Toggle mute: m
+   Move left: a
+   Move right: d
+   Move up: w
+   Move down: s
+   Long-range attack: Mouse1
+   Close-range attack: Mouse3
+
+   [Record]
+   # Directory to write record of game states, leave blank to disable.
+   Directory:
+   # Number of snapshots per second. This is preferably from 3 to 60.
+   Frequency: 30
+
+   [Server]
+   # Enabling remote control will disable control via keyboard and mouse.
+   Enable: no
+   Host: localhost
+   Port: 42069
+   # Timeout on blocking socket operations, in seconds.
+   Timeout: 1.0
+   # Disable graphics and sound (only if socket server is enabled).
+   Headless: no
+
+By default, Brutal Maze also then tries to read site (system-wide)
+and user configuration.
+
+Site Config File Location
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Apple macOS: ``/Library/Application Support/brutalmaze/settings.ini``
+* Other Unix-like: ``$XDG_CONFIG_DIRS/brutalmaze/settings.ini`` or
+  ``/etc/xdg/brutalmaze/settings.ini``
+* Microsoft Windows:
+
+    * XP: ``C:\Documents and Settings\All Users\Application Data\brutalmaze\settings.ini``
+    * Vista: Fail! (``C:\ProgramData`` is a hidden *system* directory,
+      however if you use Windows Vista, please file an issue telling us
+      which error you receive)
+    * 7 and above: ``C:\ProgramData\brutalmaze\settings.ini``
+
+User Config File Location
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Apple macOS: ``~/Library/Application Support/brutalmaze/settings.ini``
+* Other Unix-like: ``$XDG_CONFIG_HOME/brutalmaze/settings.ini`` or
+  ``~/.config/brutalmaze/settings.ini``
+* Microsoft Windows (roaming is not supported until someone requests):
+
+    * XP: ``C:\Documents and Settings\<username>\Application Data\brutalmaze\settings.ini``
+    * Vista and above: ``C:\Users\<username>\AppData\Local\brutalmaze\settings.ini``
+
+Command-Line Arguments
+----------------------
+
+.. code-block:: console
+
+   $ brutalmaze --help
+   usage: brutalmaze [options]
+
+   optional arguments:
+     -h, --help            show this help message and exit
+     -v, --version         show program's version number and exit
+     --write-config [PATH]
+                           write default config and exit, if PATH not specified use stdout
+     -c PATH, --config PATH
+                           location of the configuration file
+     -s X Y, --size X Y    the desired screen size
+     -f FPS, --max-fps FPS
+                           the desired maximum FPS
+     --mute, -m            mute all sounds
+     --unmute              unmute sound
+     --music-volume VOL    between 0.0 and 1.0
+     --space-music         use space music background
+     --default-music       use default music background
+     --touch               enable touch-friendly control
+     --no-touch            disable touch-friendly control
+     --record-dir DIR      directory to write game records
+     --record-rate SPF     snapshots of game state per second
+     --server              enable server
+     --no-server           disable server
+     --host HOST           host to bind server to
+     --port PORT           port for server to listen on
+     -t TIMEOUT, --timeout TIMEOUT
+                           socket operations timeout in seconds
+     --head                run server with graphics and sound
+     --headless            run server without graphics or sound
+
+First, Brutal Mazes read the default settings, then it try to read site and
+user config whose locations are shown above.  These files are listed as fallback
+of the ``--config`` option and their contents are fallback for other options
+(if they are absent default values are used instead).  We don't support control
+configuration via CLI because that is unarguably ugly.
+
+If ``--config`` option is set, Brutal Maze parse it before other command-line
+options.  Later-read preferences will override previous ones.