Issue 133 - Add README to sitescripts repository

README.md

Index: README.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..f0fdf6600b808b31c648dd8ca9d6f9a049eb83a0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+# Sitescripts
+
+## Introduction
+
+The sitescripts repository contains many of the server side Python scripts that
+we use. There are both web handlers, which can be used via the multiplexer, and
+scripts that perform other tasks.
+
+The scripts are often unrelated and as such will not all be documented here. For
+more information about the individual scripts you will need to look at their
+included README files. (For undocumented scripts you will need to either look at
+the code itself, or refer to the issue numbers as mentioned in the related
+commits.)
+
+
+## sitescripts.ini
+
+Many of the scripts included in this repository need some configuration in order
+to work. For this there is a shared configuration file called `sitescripts.ini`.
+The file contains different sections for the different scripts and some shared
+configuration.
+
+The configuration file can be placed in a number of locations:

[Wladimir Palant, 2015/10/05 11:22:20]

Not just that, the code will actually look for it in that specific order. So if
~/.sitescripts exists then it shadows all the other locations.

[kzar, 2015/10/06 13:00:13]

Done.

+
+1.) ~/.sitescripts

[Sebastian Noack, 2015/10/05 10:56:57]

Nit: Using closing parenthesis for numbered lists in markdown looks weird to me.
I just tested it, and in fact, this syntax isn't recognized by GitHub.

[kzar, 2015/10/06 13:00:12]

Done.

+2.) ~/sitescripts.ini
+3.) /etc/sitescripts,

[Sebastian Noack, 2015/10/05 10:56:57]

I guess the trailing comma is a typo?

[kzar, 2015/10/06 13:00:13]

Done.

+4.) /etc/sitescripts.ini
+
+_There is also an environment variable `SITESCRIPTS_CONFIG` that can be used to
+provide a custom path for the configuration._

[Wladimir Palant, 2015/10/05 11:22:20]

Please note explicitly that it will override the default configuration paths -
so the individual configuration files aren't being merged or anything like that.

[kzar, 2015/10/06 13:00:12]

Done.

+
+The `DEFAULT` section contains some of the more generic configuration options
+that are shared by the various scripts.
+
+The `multiplexer` section is used to configure which URL handlers should be
+included by the multiplexing web server. Each option key specifies an URL
+handling function, the values are not used. (So should be left blank.)
+
+We won't go into the other sections of the configuration file here, but for an
+example that includes them all take a look at `.sitescripts.example`.
+
+
+## Multiplexer
+
+Many of the scripts in this repository are URL handlers which are used when we
+need to dynamically handle web requests to our servers. For example, we might
+need to send an email after a web request has been received.
+
+These scripts are written in a standard way, using some of the decorators and

[Sebastian Noack, 2015/10/05 10:56:57]

I think it makes sense to explicitly refer to WSGI and/or PEP-333 as the
standard here.

[kzar, 2015/10/06 13:00:13]

Done.

+utilities inside `sitescripts.web` so that they can be used by the multiplexer.
+The multiplexer includes the URL handling function for each entry included in
+the `multiplexer` section of the configuration file and provides a WSGI app that
+serves them all.
+
+This WSGI app can then be served by `multiplexer.fcgi` in production and
+`multiplexer.py` in development.

[Wladimir Palant, 2015/10/05 11:22:20]

Probably mention explicitly that multiplexer.py is a stand-alone server whereas
multiplexer.fcgi is merely an FCGI script? Also, the latter requires flup
whereas the latter doesn't have any dependencies but installing werkzeug will
add debugging tools.

[kzar, 2015/10/06 13:00:13]

Done.

+
+So, to test any of the URL handlers in development, simply include their names
+in your configuration file and then type `python multiplexer.py`. A local web
+server should then be running on port 5000.