hgwebdir_wsgi: update script and expand help

I've updated the script to reflect changes in Mercurial and to include a much
more through installation guide with configuration examples and details on how
to configure IIS. I've used the script to set up a working server from scratch.

contrib/win32/hgwebdir_wsgi.py

@@ -1,96 +1,133 b''
 # An example WSGI script for IIS/isapi-wsgi to export multiple hgweb repos
-# Copyright 2010 Sune Foldager <[e-mail]>
+# Copyright 2010-2016 Sune Foldager <[e-mail]>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 #
 # Requirements:
-# - Python 2.6
-# - PyWin32 build 214 or newer
-# - Mercurial installed from source (python setup.py install)
-# - IIS 7
-#
-# Earlier versions will in general work as well, but the PyWin32 version is
-# necessary for win32traceutil to work correctly.
+# - Python 2.7, preferably 64 bit
+# - PyWin32 for Python 2.7 (32 or 64 bit)
+# - Mercurial installed from source (python setup.py install) or download the
+#   python module installer from https://www.mercurial-scm.org/wiki/Download
+# - IIS 7 or newer
 #
 #
 # Installation and use:
 #
-# - Download the isapi-wsgi source and run python setup.py install:
-#   http://code.google.com/p/isapi-wsgi/
+# - Download or clone the isapi-wsgi source and run python setup.py install.
+#   https://github.com/hexdump42/isapi-wsgi
+#
+# - Create a directory to hold the shim dll, config files etc. This can reside
+#   inside the standard IIS directory, C:\inetpub, or anywhere else. Copy this
+#   script there.
 #
 # - Run this script (i.e. python hgwebdir_wsgi.py) to get a shim dll. The
 #   shim is identical for all scripts, so you can just copy and rename one
-#   from an earlier run, if you wish.
+#   from an earlier run, if you wish. The shim needs to reside in the same
+#   directory as this script.
+#
+# - Start IIS manager and create a new app pool:
+#   .NET CLR Version: No Managed Code
+#   Advanced Settings: Enable 32 Bit Applications, if using 32 bit Python.
+#   You can adjust the identity and maximum worker processes if you wish. This
+#   setup works fine with multiple worker processes.
 #
-# - Setup an IIS application where your hgwebdir is to be served from.
-#   On 64-bit systems, make sure it's assigned a 32-bit app pool.
+# - Create an IIS application where your hgwebdir is to be served from.
+#   Assign it the app pool you just created and point its physical path to the
+#   directory you created.
+#
+# - In the application, remove all handler mappings and setup a wildcard script
+#   handler mapping of type IsapiModule with the shim dll as its executable.
+#   This file MUST reside in the same directory as the shim. The easiest way
+#   to do all this is to close IIS manager, place a web.config file in your
+#   directory and start IIS manager again. The file should contain:
 #
-# - In the application, setup a wildcard script handler mapping of type
-#   IsapiModule with the shim dll as its executable. This file MUST reside
-#   in the same directory as the shim. Remove all other handlers, if you wish.
+#   <?xml version="1.0" encoding="UTF-8"?>
+#   <configuration>
+#       <system.webServer>
+#           <handlers accessPolicy="Read, Script">
+#               <clear />
+#               <add name="hgwebdir" path="*" verb="*" modules="IsapiModule"
+#                    scriptProcessor="C:\your\directory\_hgwebdir_wsgi.dll"
+#                    resourceType="Unspecified" requireAccess="None"
+#                    preCondition="bitness64" />
+#           </handlers>
+#       </system.webServer>
+#   </configuration>
+#
+#   Where "bitness64" should be replaced with "bitness32" for 32 bit Python.
+#
+# - Edit ISAPI And CGI Restrictions on the web server (global setting). Add a
+#   restriction pointing to your shim dll and allow it to run.
 #
-# - Make sure the ISAPI and CGI restrictions (configured globally on the
-#   web server) includes the shim dll, to allow it to run.
+# - Create a configuration file in your directory and adjust the configuration
+#   variables below to match your needs. Example configuration:
+#
+#   [web]
+#   style = gitweb
+#   push_ssl = false
+#   allow_push = *
+#   encoding = utf8
 #
-# - Adjust the configuration variables below to match your needs.
+#   [server]
+#   validate = true
+#
+#   [paths]
+#   repo1 = c:\your\directory\repo1
+#   repo2 = c:\your\directory\repo2
+#
+# - Restart the web server and see if things are running.
 #
 
 # Configuration file location
-hgweb_config = r'c:\src\iis\hg\hgweb.config'
+hgweb_config = r'c:\your\directory\wsgi.config'
 
 # Global settings for IIS path translation
 path_strip = 0   # Strip this many path elements off (when using url rewrite)
 path_prefix = 1  # This many path elements are prefixes (depends on the
                  # virtual path of the IIS application).
 
 import sys
 
 # Adjust python path if this is not a system-wide install
-#sys.path.insert(0, r'c:\path\to\python\lib')
+#sys.path.insert(0, r'C:\your\custom\hg\build\lib.win32-2.7')
 
 # Enable tracing. Run 'python -m win32traceutil' to debug
 if getattr(sys, 'isapidllhandle', None) is not None:
     import win32traceutil
     win32traceutil.SetupForPrint # silence unused import warning
 
-# To serve pages in local charset instead of UTF-8, remove the two lines below
-import os
-os.environ['HGENCODING'] = 'UTF-8'
-
-
 import isapi_wsgi
-from mercurial import demandimport; demandimport.enable()
 from mercurial.hgweb.hgwebdir_mod import hgwebdir
 
 # Example tweak: Replace isapi_wsgi's handler to provide better error message
 # Other stuff could also be done here, like logging errors etc.
 class WsgiHandler(isapi_wsgi.IsapiWsgiHandler):
     error_status = '500 Internal Server Error' # less silly error message
 
 isapi_wsgi.IsapiWsgiHandler = WsgiHandler
 
 # Only create the hgwebdir instance once
 application = hgwebdir(hgweb_config)
 
 def handler(environ, start_response):
 
     # Translate IIS's weird URLs
     url = environ['SCRIPT_NAME'] + environ['PATH_INFO']
     paths = url[1:].split('/')[path_strip:]
     script_name = '/' + '/'.join(paths[:path_prefix])
     path_info = '/'.join(paths[path_prefix:])
     if path_info:
         path_info = '/' + path_info
     environ['SCRIPT_NAME'] = script_name
     environ['PATH_INFO'] = path_info
 
     return application(environ, start_response)
 
 def __ExtensionFactory__():
     return isapi_wsgi.ISAPISimpleHandler(handler)
 
 if __name__=='__main__':
     from isapi.install import ISAPIParameters, HandleCommandLine
     params = ISAPIParameters()
     HandleCommandLine(params)