virtualenv and documentation tutorials

[anita kean]

I just sent this message to the turbogears mailing list
by mistake instead of here. Sorry!
Here it goes again:

There's a sort of inconsistency among the docs tutorials about
whether or not work is done in a virtual environment.

The "How to install TurboGears2" document (DownloadInstall)
includes the item "Setting up a Virtual Environment", not listed as
optional, and illustrates the "(tg2env)$" prompt as a sign that the
virtualenv having been activated.

Then (till I changed it) proceeded to illustrate shell commands
with a regular prompt. -

The next section, Quickstarting a TG2 project,
made no reference to a virtualenv - so last week I inserted
a statement at the top that if tg2 had been installed in a
virtual env, it was assumed it had now been activated.
(and linked back to the process of activation).

The wiki20 docs don't mention virtualenv,
or show any tg2env prefix on the prompt, but for example
the two tutorials in Extensions.Geo docs do - every shell
prompt there has the (tg2env) prefix.

A recursive grep on the docs directories shows that the only
occurrence of the prefix is in:
* main/DownloadInstall.rst
* main/Extensions/Geo/TileCacheTutorial.rst
* main/Extensions/Geo/MapFishTutorial.rst

I'm going through the wiki20 and toscawidgets tutorials
converting SA setup to declarative, and wondering
what the policy is:
- all tutorials explicitlly assume virtualenv?
- none do?
- it's up to the whim of the documentor?

I'm happy to insert that prompt in the wiki20 and toscawidgets
tutorials if you want.

--
Anita

[Lee McFadden]

On Sat, Feb 21, 2009 at 5:16 PM, anita kean <ak...@clear.net.nz> wrote:
>
> I'm going through the wiki20 and toscawidgets tutorials
> converting SA setup to declarative, and wondering
> what the policy is:
> - all tutorials explicitlly assume virtualenv?
> - none do?
> - it's up to the whim of the documentor?
>
> I'm happy to insert that prompt in the wiki20 and toscawidgets
> tutorials if you want.
>

To prevent a lot of repetition I think there should be a note at the
top of the tutorials (whether they currently include the prompt or
not) that a virtualenv is implicitly assumed to be active, along with
a link to the initial turbogears installation doc covering the
reasoning and instructions for setting up a virtualenv.

--
Lee McFadden

blog: http://www.splee.co.uk
rejaw: http://rejaw.com/splee
twitter: http://twitter.com/splee

[Sanjiv Singh]

Hi Anita,

This is probably because these tutorials were created *after*
virtualenv became the recommended installation method for tg2. But I
agree with you that we need to be consistent across all the docs.

regards
Sanjiv