changeset 1238:be94a085972d

docs: less redundant redundancy, some fixes
author Thomas Waldmann <tw AT waldmann-edv DOT de>
date Sat, 14 Jan 2012 23:33:24 +0100
parents bda50ecd2e35
children 7d2a51d05e73 95abf895be4f
files docs/admin/install.rst docs/admin/requirements.rst docs/admin/serve.rst docs/devel/development.rst
diffstat 4 files changed, 27 insertions(+), 40 deletions(-) [+]
line wrap: on
line diff
--- a/docs/admin/install.rst	Sat Jan 14 22:43:16 2012 +0100
+++ b/docs/admin/install.rst	Sat Jan 14 23:33:24 2012 +0100
@@ -9,15 +9,15 @@
 You can use one of two repository URLs (there is little difference between them),
 and either use Mercurial to keep a constantly updated copy of the code or download an archive of the files in tar.gz format:
-Example using Mercurial with the first URL::
+Using Mercurial to clone one of our repos::
  hg clone moin-2.0
- hg up -C default  # update workdir to "default" branch
+ OR
+ hg clone moin-2.0
-Example using Mercurial with the second URL::
+Now make sure your work dir is using the default branch::
- $ hg clone moin-2.0
- hg up -C default  # update workdir to "default" branch
+ hg up -C default
 Alternatively, visit with your web browser and download the archive
 (usually for the "default" branch) and unpack it.
@@ -32,11 +32,10 @@
 Please make sure you have `virtualenv` installed (it includes `pip`).
-Please make sure you have virtualenv installed (it includes pip).
 If you just want to run moin in-place in your mercurial working directory
-with your normal system installation of Python,
-run the following command from your mercurial moin2
-working directory (you should not run this as an administrator; use your standard user account)::
+with your normal system installation of Python, run the following command
+from your mercurial moin2 working directory (you should not run this as an
+administrator/root user; use your standard user account)::
  ./quickinstall  # for Linux (or other posix OS's)
  # or
@@ -46,12 +45,17 @@
 create a virtual environment for MoinMoin and then install moin2 including all dependencies into that directory.
 `pip` will automatically fetch all dependencies from PyPI and install them, so this may take a while.
 It will also compile the translations (`*.po` files) to binary `*.mo` files.
 Please review the output of the quickinstall script, and check whether there were fatal errors.
 If you have a bad network connection that makes the downloads fail, you can try to do the steps in quickinstall manually.
 Further, the quickinstall script will create a `moin` script for your
 platform which you can use for starting the built-in server or invoke moin script commands.
 After you activated the virtual environment, the built-in server script (named `moin`) will be in the standard PATH,
 so you can just run the command `moin` verbatim on the command line.
 Note: in this special mode, it won’t copy the MoinMoin code to the env/ directory,
 it will run everything from your work dir, so you can modify code and directly try it out
 (you only need to do this installation procedure once).
@@ -59,32 +63,32 @@
 Using a different Python or a different virtualenv directory
-See the `quickinstall` script and just modify the following lines as needed before
-running it::
-    DIR=env
-    PYTHON=python
 For example, if you want to use `PyPy` and want to name the virtualenv directory `env-pypy`,
+    # for linux
 That way, you can test with different versions of Python in different virtualenv directories within your moin2 workdir.
-Entering the virtual env
-To enter your virtual environment::
+Activating the virtual env
  source env/bin/activate  # for linux (or other posix OSes)
  # or
  env\Scripts\activate.bat  # for windows
+IMPORTANT: you always need to activate the virtual environment before running
+anything that executes moin code! Otherwise it won't find the moin command,
+nor the moin code nor the libraries it needs. Also, if you want to install
+additional software into the virtual environment, activate it before running pip!
 Initializing index and/or storage
 If you have an existing storage AND a valid index (for this storage’s content, and for this moin version),
 you can skip this section.
 If you start from scratch (no storage created yet, and no index created yet),
 you need to create an (empty) storage and an (empty) index::
@@ -122,12 +126,8 @@
  sudo apt-get install libjpeg62-dev  # Ubuntu / Debian-based
  yum install libjpeg-turbo-devel  # Fedora / Redhat-based
-Now install PIL into your virtual environment::
+Now activate your virtual environment and install PIL into it::
- # enter your virtual environment:
- source env/bin/activate  # for linux (or other posix OSes)
- # install Python Imaging Library:
  pip install pil # for linux (or other posix OSes)
@@ -167,3 +167,4 @@
 a packaging issue).  Other users have resorted to installing PIL 1.1.6 in the
 main Python directory using the Windows installers available at
--- a/docs/admin/requirements.rst	Sat Jan 14 22:43:16 2012 +0100
+++ b/docs/admin/requirements.rst	Sat Jan 14 23:33:24 2012 +0100
@@ -5,13 +5,12 @@
 MoinMoin requires Python >= 2.6 and < 3.0.
 We usually test using CPython and this is what we recommend.
-You can also try PyPy: PyPy >= 1.6 seems to work well with moin.
-In order to use PyPy, modify the quickinstall script so that the `PYTHON` variable equals `pypy`, i.e. PYTHON=pypy.
+You can also try PyPy: PyPy >= 1.6 seems to work with moin.
-You can use any server compatible with WSGI with moin. Examples:
+For moin, you can use any server compatible with WSGI:
 * the builtin "moin" server is recommended for desktop wikis, testing,
   debugging, development, adhoc-wikis, etc.
--- a/docs/admin/serve.rst	Sat Jan 14 22:43:16 2012 +0100
+++ b/docs/admin/serve.rst	Sat Jan 14 23:33:24 2012 +0100
@@ -15,15 +15,6 @@
 are running a desktop wiki or doing moin development, just use your normal
 login user.
-Entering the virtual env
-If you installed MoinMoin to a virtualenv, you need to activate it first. Doing so will
-find the moin script, the moin code, and all its library dependencies::
- source env/bin/activate  # for Linux (or other posix OS's)
- # or
- env\Scripts\activate.bat  # for windows
 Running the built-in server
 Then you can run the moin built-in server by::
--- a/docs/devel/development.rst	Sat Jan 14 22:43:16 2012 +0100
+++ b/docs/devel/development.rst	Sat Jan 14 23:33:24 2012 +0100
@@ -176,11 +176,7 @@
 Running the tests
-To run the tests you first need to enter your virtualenv::
-    . env/bin/activate
-To run tests, enter::
+To run the tests, activate your virtual env and run::
     py.test  # runs all tests
     py.test -k somekeyword  # just run the tests matching somekeyword