Adjustment to Pylons Docs "getting started" page

[Eric Ongerth]

Hi Pylons team,

In reference to this page:
http://pylonshq.com/docs/en/0.9.7/gettingstarted/

I was going to submit the following comments at the end of that page,
but the text there says that comments will be deleted as the concerns
they bring up are addressed, and there are comments all the way back
to February so I figured that might be defunct. Perhaps something
should be changed there to avoid the appearance of an underactive
project. In any case, is it OK to submit the following here or should
such things be directed to the main Pylons discussion list? In
particular, comments that relate to documentation updates/corrections.

Running the go-pylons.py script currently fails on a clean Windows 7
installation if the command shell is not opened with administrator
privileges. It is important to note that there are two failure cases,
one innocuous (and which we could expect anyone to work around
proficiently) and one less so. Unfortunately I have not been able to
perfectly reproduce what conditions determine which failure case you
get.

Case #1 is innocuous: the script fails right away complaining that it
needs to be run under elevated privileges. It's safe to assume that
anyone working with this knows what to do at that point, go back and
try again with an admin-level command shell. No real problem there
(but the Getting Started page of the Pylons docs should have a line
added to indicate that an elevated shell is required).

Case #2 is more problematic: the script gets through its first
download or two and starts trying to install things, then fails with
an error about how "wb" is not an acceptable file mode. The error
does not directly mention elevation of privileges or anything.

Ideally people will still draw the correct conclusion in Case #2 and
try again with admin privileges, which works fine. Nonetheless, the
docs IMO need an extra line to mention this, and moreover I think the
script or some of the code that it calls should be modified to catch
the above error and give a more descriptive error message.

Thanks! I currently have the good fortune of being allowed to use
Pylons as the framework for a class project so I'm looking forward to
catching up on it after a long time off.

- Eric

[Eric Ongerth]

Correction. I was unknowingly conflating two separate issues.

One is the need for elevated privileges in the shell window. Yes,
that is necessary but it has nothing to do with the failure of the go-
pylons.py script to complete.

It turns out the script always fails on its first run, something to do
with just not checking whether a path exists before trying to use it
or something, because it hits an "invalid filename" error. And it
succeeds if you simply issue the same command a second time.