[svn r57587] merging doc and tool changes from release branch

svn merge -r 57540:HEAD release/0.9.x

--HG--
branch : trunk

MANIFEST

@@ -63,6 +63,7 @@ py/apigen/tracer/tracer.py
 py/bin/_docgen.py
 py/bin/_findpy.py
 py/bin/_genscripts.py
+py/bin/gendoc.py
 py/bin/py.cleanup
 py/bin/py.countloc
 py/bin/py.lookup
@@ -115,6 +116,7 @@ py/cmdline/pyrest.py
 py/cmdline/pytest.py
 py/cmdline/pywhich.py
 py/cmdline/testing/__init__.py
+py/cmdline/testing/test_cmdline.py
 py/cmdline/testing/test_generic.py
 py/code/__init__.py
 py/code/code.py

py/LICENSE

@@ -19,6 +19,7 @@ Contributors include::
     Chris Lamb 
     Harald Armin Massa
     Ralf Schmitt
+    Martijn Faassen
     Ian Bicking 
     Jan Balster
     Grig Gheorghiu

py/bin/_docgen.py

@@ -1,61 +0,0 @@
-#!/usr/bin/env python
-
-""" quick tool to get documentation + apigen docs generated
-
-    given a certain targetpath, apigen docs will be placed in 'apigen',
-
-    user can choose to only build either docs or apigen docs: in this case,
-    the navigation bar will be adjusted
-"""
-
-from _findpy import py
-pypath = py.__pkg__.getpath()
-print "using pypath", pypath
-import os
-
-def run_tests(path, envvars='', args=''):
-    pytestpath = pypath.join('bin/py.test')
-    cmd = ('PYTHONPATH="%s" %s python "%s" %s "%s"' %
-            (pypath.dirpath(), envvars, pytestpath, args, path))
-    print cmd
-    errno = os.system(cmd)
-    assert not errno
-
-def build_apigen_docs(targetpath, testargs=''):
-    run_tests(pypath,
-              'APIGEN_TARGET="%s/apigen" APIGEN_DOCRELPATH="../"' % (
-               targetpath,),
-              '%s --apigen="%s/apigen/apigen.py"' % (testargs, pypath))
-
-def build_docs(targetpath, testargs):
-    docpath = pypath.join('doc')
-    run_tests(docpath, '',
-              testargs + ' --forcegen --apigen="%s/apigen/apigen.py"' % (pypath,))
-    docpath.copy(targetpath)
-
-def build_nav(targetpath, docs=True, api=True):
-    pass
-
-def build(targetpath, docs=True, api=True, testargs=''):
-    targetpath.ensure(dir=True)
-    if docs:
-        print 'building docs'
-        build_docs(targetpath, testargs)
-    if api:
-        print 'building api'
-        build_apigen_docs(targetpath, testargs)
-
-        
-if __name__ == '__main__':
-    import sys
-    if len(sys.argv) == 1:
-        print 'usage: %s <targetdir> [options]'
-        print
-        print '  targetdir: a path to a directory (created if it doesn\'t'
-        print '             exist) where the docs are put'
-        print '  options: options passed to py.test when running the tests'
-        sys.exit(1)
-    targetpath = py.path.local(sys.argv[1])
-    args = ' '.join(sys.argv[2:])
-    build(targetpath, True, True, args)
-

py/bin/gendoc.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python
+
+""" 
+build the 'py' documentation and api docs in a specified
+directory, defaulting to 'html'.  You need to be a directory
+where your "py" package is.  
+
+This script generates API documentation and static
+documentation.  The API documentation is generated by using
+the "apigen" facility of the py lib which currently only works
+on windows. 
+"""
+
+import sys
+sys.path.insert(0, '.')
+
+import py
+import os
+
+def sysexec(cmd):
+    print "executing", cmd
+    os.system(cmd)
+
+if __name__ == '__main__':
+    pydir = py.path.local().join("py")
+    assert pydir.check(dir=1), "py directory not found"
+    pypath = py.path.local(py.__file__).dirpath()
+    assert pydir == pypath, "directory %s and %s differ" %(pydir, pypath)
+    
+    args = sys.argv[1:]
+    if not args:
+        htmldir = py.path.local('html')
+    else:
+        htmldir = py.path.local(sys.argv.pop(0))
+
+    print "generating docs into", htmldir
+    print "pypath", pypath
+    pytest = pypath.join("bin/py.test")
+    assert pytest.check()
+
+    print 
+    print "*" * 30, "apigen", "*"*30
+    apigendir = htmldir.join("apigen")
+    env = 'DOCPATH="%s" APIGENPATH="%s"' %(htmldir, apigendir)
+    if apigendir.check():
+        print apigendir, "exists, not re-generating - remove to trigger regeneration"
+    else:
+        sysexec('%(env)s %(pytest)s --apigen=%(pypath)s/apigen/apigen.py py' % locals())
+    print 
+    print "*" * 30, "static generation", "*" * 30
+    sysexec('%(env)s %(pytest)s --forcegen %(pypath)s/doc' % locals())

py/cmdline/pycountloc.py

@@ -11,7 +11,6 @@ starting from a list of paths given on the command line (starting from the
 current working directory). Distinguish between test files and normal ones and
 report them separately.
 """
-from _findpy import py 
 import py
 from py.compat import optparse
 from py.__.misc.cmdline.countloc import countloc 

py/doc/contact.txt

@@ -1,55 +1,20 @@
 py lib contact and communication 
 ===================================
 
-.. contents::
-.. sectnum::
 
-IRC Channel #pylib on irc.freenode.net 
+- **#pylib on irc.freenode.net**: you are welcome
---------------------------------------------
+  to lurk or ask questions in this IRC channel, it also tracks py lib commits. 
 
-The #pylib channel on freenode displays all commits to the py lib
+- `py-dev developers list`_ development mailing list.  Good for reporting bugs, feature questions, discussing issues.  Usually sees between 1 and 10 posts per week. 
-and you are welcome to lurk or to ask questions there! 
 
-`py-dev`_ developers mailing list
+- `py-svn general commit mailing list`_ to follow all development commits. 
------------------------------------ 
 
-If you see bugs and/or can provide patches, please
+- `development bug/feature tracker`_ this roundup instance serves to file bugs and track issues.  
-subscribe to the `py-dev developers list`_. 
-As of Febrary 2007 it has medium to low traffic. 
 
+- `merlinux.eu`_ offers tutorials and commercial support for
+  py.test and the py lib in general. 
 
-`py-svn`_ commit mailing list
+.. _`merlinux.eu`: http://merlinux.eu
------------------------------------ 
-
-If you'd like to see ongoing development commits,
-please subscribe to: 
-
-    `py-svn general commit mailing list`_ 
-
-This list (as of February 2007) has medium to high traffic. 
-
-
-`development bug/feature tracker`_ 
----------------------------------------------
-
-This (somewhat old) roundup instance still serves 
-to file bugs and track issues.  However, we also 
-keep a list of "TODOs" in various directories. 
-
-
-Coding and communication 
-------------------------
-
-We are practicing what could be called documentation, 
-vision, discussion and automated-test driven development. 
-In the `future`_ book we try to layout visions and ideas for
-the near coding feature to give a means for preliminary
-feedback before code hits the ground. 
-
-With our `coding style`_ we are mostly following 
-cpython guidance with some additional restrictions
-some of which projects like twisted_ or zope3_ have 
-adopted in similar ways. 
 
 .. _`zope3`: http://zope3.zwiki.org/
 .. _twisted: http://www.twistedmatrix.org 
@@ -61,13 +26,13 @@ adopted in similar ways.
 get an account on codespeak  
 --------------------------- 
 
-codespeak_ is employing a liberal committing scheme.  If you know 
+codespeak_ is where the subversion repository is hosted.  If you know 
 someone who is active on codespeak already or you are otherwise known in 
-the community then you will most probably just get access.  But even if 
+the community (see also: FOAF_) you will get access.  But even if 
-you are new to the python developer community you may still get one if 
+you are new to the python developer community please come to the IRC 
-you want to improve things and can be expected to honour the 
+or the mailing list and ask questions, get involved. 
-style of coding and communication. 
 
+.. _FOAF: http://en.wikipedia.org/wiki/FOAF
 .. _`coding style`: coding-style.html 
 .. _us: http://codespeak.net/mailman/listinfo/py-dev
 .. _codespeak: http://codespeak.net/

py/doc/download.txt

@@ -24,7 +24,7 @@ code automatically during the above install).
 Downloading a tar/zip archive and installing that
 ===================================================
 
-Go to the project pages and download a tar or zip file:
+Go to the python package index (pypi) and download a tar or zip file:
 
     http://pypi.python.org/pypi/py/
 
@@ -48,33 +48,46 @@ and documentation source::
 
     svn co http://codespeak.net/svn/py/release/0.9.x py-0.9.x
 
-You should then be able to issue::
+You can then issue::
 
     python setup.py develop 
 
-and work with the local version.  
+in order to work with your checkout version. 
 
-If this doesn't work for you then you can also 
+other interesting svn checkout points::
-source (linux) or execute (windows) some scripts
-that set environment variables for using your checkout. 
-You can execute: 
-
-    python ~/path/to/checkout/py/env.py 
-
-or on windows:  
-
-    \\path\\to\\checkout\\py\\env.cmd
-
-to get settings for PYTHONPATH and PATH.
-
-
-py subversion directory structure
-=================================
-
-The directory release layout of the repository is
-going to follow this scheme:: 
 
     http://codespeak.net/
-        svn/py/dist         # latest stable (may or may not be a release) 
         svn/py/release      # release tags and branches
+        svn/py/dist         # latest stable (may or may not be a release) 
         svn/py/trunk        # head development / merge point
+
+
+Working with multiple py lib versions / svn externals
+=======================================================
+
+If you happen to have multiple versions of the py lib 
+around or you ship the py lib as an svn-external to 
+then you might want to use py lib scripts more directly.
+For example if you have a project layout like this::
+
+    mypkg/
+        subpkg1/
+            tests/
+        tests/
+    py/ # as svn-external, could be specific tag/version
+
+then you want to make sure that the actual local py lib is used
+and not another system-wide version.  For this you need to add
+``py/bin`` or ``py\bin\win32`` respectively to your system's PATH settings. 
+
+You can do this by executing (on windows) a script to set the environment::
+
+    c:\\path\to\checkout\py\env.cmd
+
+or on linux/osx you can add something like this to your shell
+initialization::
+
+    eval `python ~/path/to/checkout/py/env.py`
+
+to get good settings for PYTHONPATH and PATH.
+

py/doc/index.txt

@@ -4,7 +4,7 @@ py lib documentation
     The py lib is a development support library featuring
     py.test, ad-hoc distributed execution, micro-threads
     (greenlets) and uniform local path and svn abstractions.  
-    Works on Linux, Windows and OSX, Python versions 
+    It works on Linux, Windows and OSX, Python versions 
     2.3, 2.4, 2.5 and 2.6. 
 
 `Download and Installation`_ 

py/doc/release-0.9.2.txt

@@ -3,9 +3,9 @@ py lib 0.9.2: bugfix release
 
 Welcome to the 0.9.2 py lib and py.test release - 
 mainly fixing Windows issues, providing better
-packaging and integration with setuptools. 
+packaging and integration with setuptools.
 
-Here is a quick summary of what it provides: 
+Here is a quick summary of what the py lib provides: 
 
 * py.test: cross-project testing tool with many advanced features
 * py.execnet: ad-hoc code distribution to SSH, Socket and local sub processes
@@ -16,6 +16,8 @@ Here is a quick summary of what it provides:
 
 See here for more information:
 
+Pypi pages: http://pypi.python.org/pypi/py/
+
 Download/Install:   http://codespeak.net/py/0.9.2/download.html
 
 Documentation/API:  http://codespeak.net/py/0.9.2/index.html

setup.py

@@ -138,9 +138,9 @@ def main():
                              'apigen/style.css',
                              'apigen/todo-apigen.txt',
                              'apigen/todo.txt',
-                             'bin/_docgen.py',
                              'bin/_findpy.py',
                              'bin/_genscripts.py',
+                             'bin/gendoc.py',
                              'bin/py.cleanup',
                              'bin/py.countloc',
                              'bin/py.lookup',