update and fix docs for installation

- rework installation
- add a new FAQ entry related to issue58 Windows/setuptools/multiprocess
- strike api/source references

--HG--
branch : trunk

.hgignore

@@ -17,3 +17,4 @@ syntax:glob
 build/
 dist/
 py.egg-info
+issue/

bin-for-dist/makepluginlist.py

@@ -217,7 +217,7 @@ class PluginDoc(RestWriter):
         self.links.append(('plugins', 'index.html'))
         self.links.append(('get in contact', '../../contact.html'))
         self.links.append(('checkout the py.test development version', 
-            '../../download.html#checkout'))
+            '../../install.html#checkout'))
        
         if 0: # this breaks the page layout and makes large doc files
             #self.h2("plugin source code") 

doc/code.txt

@@ -2,35 +2,33 @@
 py.code: higher level python code and introspection objects
 ================================================================================
 
-The :api:`py.code` part of the pylib contains some functionality to help
+The ``py.code`` part of the pylib contains some functionality to help
 dealing with Python code objects. Even though working with Python's internal
 code objects (as found on frames and callables) can be very powerful, it's
 usually also quite cumbersome, because the API provided by core Python is
 relatively low level and not very accessible.
 
-The :api:`py.code` library tries to simplify accessing the code objects as well
+The ``py.code`` library tries to simplify accessing the code objects as well
 as creating them. There is a small set of interfaces a user needs to deal with,
 all nicely bundled together, and with a rich set of 'Pythonic' functionality.
 
-source: :source:`py/code/`
-
 Contents of the library
 =======================
 
-Every object in the :api:`py.code` library wraps a code Python object related
+Every object in the ``py.code`` library wraps a code Python object related
-to code objects, source code, frames and tracebacks: the :api:`py.code.Code`
+to code objects, source code, frames and tracebacks: the ``py.code.Code``
-class wraps code objects, :api:`py.code.Source` source snippets,
+class wraps code objects, ``py.code.Source`` source snippets,
-:api:`py.code.Traceback` exception tracebacks, :api:`py.code.Frame` frame 
+``py.code.Traceback` exception tracebacks, :api:`py.code.Frame`` frame 
-objects (as found in e.g. tracebacks) and :api:`py.code.ExceptionInfo` the
+objects (as found in e.g. tracebacks) and ``py.code.ExceptionInfo`` the
 tuple provided by sys.exc_info() (containing exception and traceback
 information when an exception occurs). Also in the library is a helper function
-:api:`py.code.compile()` that provides the same functionality as Python's
+``py.code.compile()`` that provides the same functionality as Python's
 built-in 'compile()' function, but returns a wrapped code object.
 
 The wrappers
 ============
 
-:api:`py.code.Code`
+``py.code.Code``
 -------------------
 
 Code objects are instantiated with a code object or a callable as argument,
@@ -48,9 +46,7 @@ A quick example::
   >>> str(c.source()).split('\n')[0]
   "def read(self, mode='r'):"
 
-source: :source:`py/code/code.py`
+``py.code.Source``
-
-:api:`py.code.Source`
 ---------------------
 
 Source objects wrap snippets of Python source code, providing a simple yet
@@ -71,9 +67,8 @@ Example::
   >>> str(sub).strip() # XXX why is the strip() required?!?
   'print "foo"'
 
-source: :source:`py/code/source.py`
 
-:api:`py.code.Traceback`
+``py.code.Traceback``
 ------------------------
 
 Tracebacks are usually not very easy to examine, you need to access certain
@@ -97,15 +92,13 @@ Example::
   >>> str(first.statement).strip().startswith('raise ValueError')
   True
 
-source: :source:`py/code/code.py`
+``py.code.Frame``
-
-:api:`py.code.Frame`
 --------------------
 
-Frame wrappers are used in :api:`py.code.Traceback` items, and will usually not
+Frame wrappers are used in ``py.code.Traceback`` items, and will usually not
 directly be instantiated. They provide some nice methods to evaluate code
 'inside' the frame (using the frame's local variables), get to the underlying
-code (frames have a code attribute that points to a :api:`py.code.Code` object)
+code (frames have a code attribute that points to a ``py.code.Code`` object)
 and examine the arguments.
 
 Example (using the 'first' TracebackItem instance created above)::
@@ -118,7 +111,7 @@ Example (using the 'first' TracebackItem instance created above)::
   >>> [namevalue[0] for namevalue in frame.getargs()]
   ['cls', 'path']
 
-:api:`py.code.ExceptionInfo`
+``py.code.ExceptionInfo``
 ----------------------------
 
 A wrapper around the tuple returned by sys.exc_info() (will call sys.exc_info()

doc/confrest.py

@@ -57,7 +57,7 @@ pageTracker._trackPageview();
         
     def fill_menubar(self):
         items = [
-            self.a_docref("install", "download.html"),
+            self.a_docref("install", "install.html"),
             self.a_docref("contact", "contact.html"),
             self.a_docref("changelog", "changelog.html"),
             self.a_docref("faq", "faq.html"),

doc/download.html

@@ -0,0 +1,18 @@
+<html>
+    <head>
+        <meta http-equiv="refresh" content=" 1 ; URL=install.html" />
+    </head>
+
+    <body>
+<script type="text/javascript">
+var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+</script>
+<script type="text/javascript">
+try {
+var pageTracker = _gat._getTracker("UA-7597274-3");
+pageTracker._trackPageview();
+} catch(err) {}</script>
+</body>
+</html>
+    

doc/faq.txt

@@ -120,3 +120,29 @@ and implement the `parametrization scheme of your choice`_.
 
 .. _`pytest_generate_tests`: test/funcargs.html#parametrizing-tests
 .. _`parametrization scheme of your choice`: http://tetamap.wordpress.com/2009/05/13/parametrizing-python-tests-generalized/ 
+
+
+py.test interaction with other packages
+===============================================
+
+What's up with multiprocess on Windows? 
+------------------------------------------------------------
+
+On windows the multiprocess package will instantiate sub processes 
+by pickling and thus implicitely re-import a lot of local modules. 
+Unfortuantely, setuptools-0.6.11 does not ``if __name__=='__main__'`` 
+protect its generated command line script.  This leads to infinite
+recursion when running a test that instantiates Processes.
+There are two workarounds: 
+
+* `install Distribute`_ as a drop-in replacement for setuptools 
+  and re-install py.test 
+
+* `directly use a checkout`_ which avoids all setuptools/Distribute
+  installation 
+
+.. _`directly use a checkout`: install.html#directly-use-a-checkout
+
+.. _`install distribute`: http://pypi.python.org/pypi/distribute#installation-instructions
+
+

doc/install.txt

@@ -7,23 +7,29 @@
 
     Latest Release, see `PyPI project page`_
 
-using easy_install 
+using easy_install (via Distribute or setuptools)
 ===================================================
 
-With a working `setuptools installation`_ or `distribute installation`_ 
+It is recommended to use `Distribute for installation`_ as a drop-in
+replacement for setuptools_. While setuptools should work well on
+Python2 versions, `Distribute`_ allows to install py.test on Python3 
+and it avoids issue on Windows.  With either packaging system 
 you can type::
 
     easy_install -U py 
 
-to get the latest release of the py lib.  The ``-U`` switch
+to get the latest release of the py lib and py.test.  The ``-U`` switch
 will trigger an upgrade if you already have an older version installed. 
 On Linux systems you may need to execute the command as superuser and
 on Windows you might need to write down the full path to ``easy_install``. 
+
 The py lib and its tools are expected to work well on Linux,
 Windows and OSX, Python versions 2.4, 2.5, 2.6 through to
-the Python3 versions 3.0 and 3.1. 
+the Python3 versions 3.0 and 3.1.  Jython 
 
 .. _mercurial: http://mercurial.selenic.com/wiki/
+.. _`Distribute`: 
+.. _`Distribute for installation`: http://pypi.python.org/pypi/distribute#installation-instructions
 .. _`distribute installation`: http://pypi.python.org/pypi/distribute
 .. _checkout:
 .. _tarball:
@@ -39,20 +45,22 @@ and documentation source with mercurial_::
 
 This currrently contains a 1.0.x branch and the 
 default 'trunk' branch where mainline development 
-takes place.  There also is a readonly subversion
+takes place. 
-checkout available::
 
+.. There also is a readonly subversion
+   checkout available which contains the latest release::
    svn co https://codespeak.net/svn/py/dist
 
-You can also go to the python package index and
+You can go to the python package index and
 download and unpack a TAR file::
 
     http://pypi.python.org/pypi/py/
 
-activating checkout with setuptools 
+
+activating a checkout with setuptools 
 --------------------------------------------
 
-With a working `setuptools installation`_ you can issue::
+With a working `Distribute`_ or setuptools_ installation you can type::
 
     python setup.py develop 
 
@@ -60,14 +68,13 @@ in order to work with the tools and the lib of your checkout.
 
 .. _`no-setuptools`:
 
-activating a checkout or tarball without setuptools 
+.. _`directly use a checkout`: 
+
+directly use a checkout or tarball
 -------------------------------------------------------------
 
-To import the py lib the ``py`` package directory needs to
+Once you got yourself a checkout_ or tarball_ you only need to 
-be on the ``$PYTHONPATH``.  If you exexute scripts directly
+set ``PYTHONPATH`` and ``PATH`` environment variables. 
-from ``py/bin/`` or ``py\bin\win32`` they will find their
-containing py lib automatically. 
-
 It is usually a good idea to add the parent directory of the ``py`` package 
 directory to your ``PYTHONPATH`` and ``py/bin`` or ``py\bin\win32`` to your 
 system wide ``PATH`` settings.  There are helper scripts that set ``PYTHONPATH`` and ``PATH`` on your system: 
@@ -75,12 +82,12 @@ system wide ``PATH`` settings.  There are helper scripts that set ``PYTHONPATH``
 on windows execute::
 
     # inside autoexec.bat or shell startup
-    c:\\path\to\checkout\py\bin\env.cmd
+    c:\\path\to\checkout\bin\env.cmd
 
 on linux/OSX add this to your shell initialization:: 
 
     # inside .bashrc 
-    eval `python ~/path/to/checkout/py/bin/env.py` 
+    eval `python ~/path/to/checkout/bin/env.py` 
 
 both of which which will get you good settings 
 for ``PYTHONPATH`` and ``PATH``.
@@ -89,7 +96,7 @@ for ``PYTHONPATH`` and ``PATH``.
 note: scripts look for "nearby" py-lib 
 -----------------------------------------------------
 
-Note that the `command line scripts`_ will look 
+Note that all `command line scripts`_ will look 
 for "nearby" py libs, so if you have a layout like this::
 
     mypkg/
@@ -119,5 +126,5 @@ of questions or need for changes.
 
 .. _`RPM`: http://translate.sourceforge.net/releases/testing/fedora/pylib-0.9.2-1.fc9.noarch.rpm
 
-.. _`setuptools installation`: http://pypi.python.org/pypi/setuptools
+.. _`setuptools`: http://pypi.python.org/pypi/setuptools
 

doc/io.txt

@@ -9,10 +9,10 @@ execution of a program.
 IO Capturing examples
 ===============================================
 
-:api:`py.io.StdCapture`
+``py.io.StdCapture``
 ---------------------------
 
-Basic Example: 
+Basic Example::
 
   >>> import py
   >>> capture = py.io.StdCapture()
@@ -21,7 +21,7 @@ Basic Example:
   >>> out.strip() == "hello"
   True
 
-For calling functions you may use a shortcut: 
+For calling functions you may use a shortcut:: 
 
   >>> import py
   >>> def f(): print "hello"
@@ -29,14 +29,14 @@ For calling functions you may use a shortcut:
   >>> out.strip() == "hello"
   True
 
-:api:`py.io.StdCaptureFD`
+``py.io.StdCaptureFD``
 ---------------------------
 
 If you also want to capture writes to the stdout/stderr
-filedescriptors you may invoke: 
+filedescriptors you may invoke::
 
   >>> import py, sys
-  >>> capture = py.io.StdCaptureFD()
+  >>> capture = py.io.StdCaptureFD(out=False, in_=False)
   >>> sys.stderr.write("world")
   >>> out,err = capture.reset()
   >>> err

doc/misc.txt

@@ -5,7 +5,7 @@ Miscellaneous features of the py lib
 Mapping the standard python library into py 
 ===========================================
 
-The :api:`py.std` object allows lazy access to 
+The ``py.std`` object allows lazy access to 
 standard library modules.  For example, to get to the print-exception
 functionality of the standard library you can write:: 
 
@@ -21,9 +21,9 @@ Support for interaction with system utilities/binaries
 ======================================================
 
 Currently, the py lib offers two ways to interact with
-system executables. :api:`py.process.cmdexec()` invokes
+system executables. ``py.process.cmdexec()`` invokes
 the shell in order to execute a string.  The other
-one, :api:`py.path.local`'s 'sysexec()' method lets you 
+one, ``py.path.local``'s 'sysexec()' method lets you 
 directly execute a binary. 
 
 Both approaches will raise an exception in case of a return-
@@ -87,28 +87,7 @@ right version::
     binsvn = py.path.local.sysfind('svn', checker=mysvn) 
 
 
-
 Cross-Python Version compatibility helpers
 =============================================
 
-sources: 
+The ``py.builtin`` namespace provides a number of helpers that help to write python code compatible across Python interpreters, mainly Python2 and Python3.  Type ``help(py.builtin)`` on a Python prompt for a the selection of builtins.
-
-  * :source:`py/builtin/`
-
-The compat and builtin namespaces help to write code using newer python features on older python interpreters. 
-
-:api:`py.builtin`
------------------
-
-:api:`py.builtin` provides builtin functions/types that were added in later Python
-versions. If the used Python version used does not provide these builtins the
-py lib provides some reimplementations. These currently are:
-
- * enumerate
- * reversed
- * sorted
- * BaseException
- * set and frozenset (using either the builtin, if available, or the sets
-   module)
-
-:api:`py.builtin.BaseException` is just ``Exception`` before Python 2.5.

doc/path.txt

@@ -3,17 +3,17 @@ py.path
 =======
 
 The 'py' lib provides a uniform high-level api to deal with filesystems
-and filesystem-like interfaces: :api:`py.path`.  It aims to offer a central
+and filesystem-like interfaces: ``py.path``.  It aims to offer a central
 object to fs-like object trees (reading from and writing to files, adding
 files/directories, examining the types and structure, etc.), and out-of-the-box
 provides a number of implementations of this API.
 
-Path implementations provided by :api:`py.path`
+Path implementations provided by ``py.path``
 ===============================================
 
 .. _`local`: 
 
-:api:`py.path.local`
+``py.path.local``
 --------------------
 
 The first and most obvious of the implementations is a wrapper around a local
@@ -21,8 +21,8 @@ filesystem. It's just a bit nicer in usage than the regular Python APIs, and
 of course all the functionality is bundled together rather than spread over a
 number of modules.
 
-Example usage, here we use the :api:`py.test.ensuretemp()` function to create
+Example usage, here we use the ``py.test.ensuretemp()`` function to create
-a :api:`py.path.local` object for us (which wraps a directory):
+a ``py.path.local`` object for us (which wraps a directory):
 
 .. sourcecode:: pycon
 
@@ -40,17 +40,17 @@ a :api:`py.path.local` object for us (which wraps a directory):
   >>> foofile.read(1)
   'b'
 
-:api:`py.path.svnurl` and :api:`py.path.svnwc`
+``py.path.svnurl` and :api:`py.path.svnwc``
 ----------------------------------------------
 
-Two other :api:`py.path` implementations that the py lib provides wrap the
+Two other ``py.path`` implementations that the py lib provides wrap the
 popular `Subversion`_ revision control system: the first (called 'svnurl')
 by interfacing with a remote server, the second by wrapping a local checkout.
 Both allow you to access relatively advanced features such as metadata and
 versioning, and both in a way more user-friendly manner than existing other
 solutions.
 
-Some example usage of :api:`py.path.svnurl`:
+Some example usage of ``py.path.svnurl``:
 
 .. sourcecode:: pycon
 
@@ -65,7 +65,7 @@ Some example usage of :api:`py.path.svnurl`:
   >>> time.strftime('%Y-%m-%d', time.gmtime(firstentry.date))
   '2004-10-02'
 
-Example usage of :api:`py.path.svnwc`:
+Example usage of ``py.path.svnwc``:
 
 .. sourcecode:: pycon
 
@@ -125,7 +125,7 @@ specific directory.
 Working with Paths 
 .......................
 
-This example shows the :api:`py.path` features to deal with
+This example shows the ``py.path`` features to deal with
 filesystem paths Note that the filesystem is never touched,
 all operations are performed on a string level (so the paths
 don't have to exist, either):
@@ -154,7 +154,7 @@ don't have to exist, either):
   >>> p4.purebasename == "bar"
   True
 
-This should be possible on every implementation of :api:`py.path`, so
+This should be possible on every implementation of ``py.path``, so
 regardless of whether the implementation wraps a UNIX filesystem, a Windows
 one, or a database or object tree, these functions should be available (each
 with their own notion of path seperators and dealing with conversions, etc.).
@@ -189,7 +189,7 @@ Setting svn-properties
 .......................
 
 As an example of 'uncommon' methods, we'll show how to read and write
-properties in an :api:`py.path.svnwc` instance:
+properties in an ``py.path.svnwc`` instance:
 
 .. sourcecode:: pycon
 
@@ -254,7 +254,7 @@ to provide this choice (and getting rid
 of platform-dependencies as much as possible). 
 
 There is some experimental small approach 
-(:source:`py/path/gateway/`) aiming at having
+(``py/path/gateway/``) aiming at having
 a convenient Remote Path implementation. 
 
 There are various hacks out there to have

doc/test/plugin/links.txt

@@ -16,7 +16,7 @@
 .. _`pytest_figleaf.py`: http://bitbucket.org/hpk42/py-trunk/raw/trunk/_py/test/plugin/pytest_figleaf.py
 .. _`pytest_hooklog.py`: http://bitbucket.org/hpk42/py-trunk/raw/trunk/_py/test/plugin/pytest_hooklog.py
 .. _`pytest_skipping.py`: http://bitbucket.org/hpk42/py-trunk/raw/trunk/_py/test/plugin/pytest_skipping.py
-.. _`checkout the py.test development version`: ../../download.html#checkout
+.. _`checkout the py.test development version`: ../../install.html#checkout
 .. _`pytest_helpconfig.py`: http://bitbucket.org/hpk42/py-trunk/raw/trunk/_py/test/plugin/pytest_helpconfig.py
 .. _`oejskit`: oejskit.html
 .. _`doctest`: doctest.html

doc/test/quickstart.txt

@@ -5,16 +5,12 @@
 Quickstart
 ==================
 
-.. _here: ../download.html#no-setuptools
+.. _here: ../install.html
 
-
+If you have a version of ``easy_install`` (otherwise see here_) just type::
-With a `setuptools installation`_  (otherwise see here_) you can type::
 
     easy_install -U py 
 
-On Linux systems you may need to execute this as the superuser and
-on Windows you might need to write down the full path to ``easy_install``. 
-
 Now create a file ``test_sample.py`` with the following content: 
 
 .. sourcecode:: python 
@@ -63,7 +59,7 @@ a progress report and important details of the failure.
 
 .. _`contact`: ../contact.html
 .. _`automatically collected`: features.html#autocollect
-.. _download: ../download.html
+.. _install: ../install.html
 .. _features: features.html
 .. _tutorials: talks.html