[svn r38455] various merging of startup documentation

and rewriting/refactoring information and
references.  clarifying release-structure
a bit.

--HG--
branch : trunk

py/doc/TODO.txt

@@ -59,9 +59,8 @@ packaging
 
 * (DONE/c-modules don't) see if things work on Win32 (partially done) 
 
-* refine and implement `releasescheme`_ 
+* (partly DONE) refine and implement releasescheme/download
 
-.. _releasescheme: releasescheme.html
 
 APIGEN / source viewer
 -------------------------------------

py/doc/api.txt

@@ -1,19 +0,0 @@
-The py lib API 
-==============
-
-This is a placeholder for upcoming API documentation.  We
-intend to mostly generate this API description from the py
-lib's entry points, their docstrings and cross-reference it
-with its tests and examples that are already available 
-at our little `getting started`_ chapter. 
-
-Your tests are your API insurance
-=================================
-
-Tests are the primary assurance of API compatilibity.  If you
-would like to ensure some behaviour gets preserved across major
-releases you have to write a test. Note though, that the 
-documentation may state additional restrictions which
-take precedence.  
-
-.. _`getting started`: getting-started.html 

py/doc/contact.txt

@@ -1,15 +1,81 @@
 py lib contact and communication 
 ===================================
 
-* `development mailing list`_ for conceptual and coding discussions (low to medium traffic). 
+.. contents::
+.. sectnum::
 
-* `subversion commit mailing list`_ all updates to the trunk/branch source and documentation tree. 
+IRC Channel #pylib on irc.freenode.net 
+--------------------------------------------
 
-* `development bug/feature tracker`_ for filing bugs and feature requests. 
+The #pylib channel on freenode displays all commits to the py lib
+and you are welcome to lurk or to ask questions there! 
 
-* IRC Channel #pylib on irc.freenode.net 
+`py-dev`_ developers mailing list
+----------------------------------- 
 
-.. _`subversion commit mailing list`: http://codespeak.net/mailman/listinfo/py-svn
+If you see bugs and/or can provide patches, please
-.. _`development mailing list`: http://codespeak.net/mailman/listinfo/py-dev
+subscribe to the `py-dev developers list`_. 
+As of Febrary 2007 it has medium to low traffic. 
+
+
+`py-svn`_ commit mailing list
+----------------------------------- 
+
+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 
+.. _future: future/future.html 
+
+.. _`get an account`:  
+
+
+get an account on codespeak  
+--------------------------- 
+
+codespeak_ is employing a liberal committing scheme.  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 
+you are new to the python developer community you may still get one if 
+you want to improve things and can be expected to honour the 
+style of coding and communication. 
+
+.. _`coding style`: coding-style.html 
+.. _us: http://codespeak.net/mailman/listinfo/py-dev
+.. _codespeak: http://codespeak.net/
+.. _`py-dev`: 
+.. _`development mailing list`: 
+.. _`py-dev developers list`: http://codespeak.net/mailman/listinfo/py-dev 
+.. _`subversion commit mailing list`: 
+.. _`py-svn`: 
+.. _`py-svn general commit mailing list`: http://codespeak.net/mailman/listinfo/py-svn 
 .. _`development bug/feature tracker`: https://codespeak.net/issue/py-dev/ 
 

py/doc/download.txt

@@ -0,0 +1,113 @@
+Download and Installation of the py lib 
+===============================================
+
+.. contents::
+.. sectnum::
+
+Downloading a tar/zip file and installing it
+===================================================
+
+The latest stable public release: 
+
+    `download py-0.9.0.tgz`_ 
+    `download py-0.9.0.zip`_ 
+
+.. _`download py-0.9.0.tgz`: http://codespeak.net/download/py/py-0.9.0.tgz 
+.. _`download py-0.9.0.zip`: http://codespeak.net/download/py/py-0.9.0.zip 
+
+The py lib can be `globally installed via setup.py`_ 
+or `used locally`_. 
+
+
+Getting (and updating) via subversion 
+--------------------------------------------
+
+Use Subversion to checkout the latest 0.9.x stable release: 
+
+    svn co http://codespeak.net/svn/py/release/0.9.x py-0.9.x
+
+to obtain the complete code and documentation tree. 
+
+If you experience problems with the subversion checkout e.g. 
+because you have a http-proxy in between that doesn't proxy 
+DAV requests you can try to use "codespeak.net:8080" instead 
+of just "codespeak.net".  Alternatively, you may tweak 
+your local subversion installation. 
+
+If you want to follow stable snapshots 
+then you may use the equivalent of this invocation: 
+
+    svn co http://codespeak.net/svn/py/dist py-dist 
+
+
+.. _`globally installed via setup.py`:
+
+Installation via setup.py 
+------------------------------
+
+Go to your unpacked/checked out directory
+and issue: 
+
+    python setup.py install
+
+
+.. _`used locally`:
+
+Local Installation/Usage
+------------------------------
+
+You need to put the checkout-directory into your ``PYTHONPATH``
+and you want to have the ``py-dist/py/bin/py.test`` script in 
+your (unixish) system path, which lets you execute test files 
+and directories.  
+
+There is a convenient way for Bash/Shell based systems
+to setup the ``PYTHONPATH`` as well as the shell ``PATH``, insert:: 
+
+    eval `python ~/path/to/py-dist/py/env.py`
+
+into your ``.bash_profile``.  Of course, you need to
+specify your own checkout-directory. 
+
+
+.. _`svn-external scenario`: 
+
+The py lib as an svn external
+-------------------------------------------------------
+
+Add the py lib as an external to your project `DIRECTORY` 
+which contains your svn-controlled root package::
+
+    svn propedit 'svn:externals' DIRECTORY 
+
+which will open an editor where you can add 
+the following line: 
+
+    py http://codespeak.net/svn/py/dist 
+
+This will make your projcet automatically use the 
+most recent stable snapshot of the py lib.  
+
+Alternatively you may use this url for
+integrating the development version:
+
+    http://codespeak.net/svn/py/trunk 
+
+or the next one for following the e.g. the 0.9 release branch
+
+    http://codespeak.net/svn/py/release/py-0.9.x
+
+
+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/X.Y.Z    # release tags and branches
+        svn/py/trunk            # head development / merge point
+
+
+

py/doc/execnet.txt

@@ -218,8 +218,6 @@ Here are 20 lines of code making the above triangle happen::
     gw = py.execnet.SocketGateway('localhost', cls.port)
     print "initialized socket gateway to port", cls.port
 
-.. _`py API`: api.html 
-
 .. [#] There is an interesting emerging `Jail`_ linux technology 
        as well as a host of others, of course. 
 

py/doc/future/future.txt

@@ -327,7 +327,6 @@ repository that is created for each run of the tests.
 
 .. _`CPython's distutils`: http://www.python.org/dev/doc/devel/lib/module-distutils.html
 
-.. _`getting started`: ../getting-started.html 
 .. _`restructured text`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
 .. _`python standard library`: http://www.python.org/doc/2.3.4/lib/lib.html
 .. _`xpython EuroPython 2004 talk`: http://codespeak.net/svn/user/hpk/talks/xpython-talk.txt

py/doc/getting-started.txt

@@ -1,127 +0,0 @@
-Getting started with the py lib 
-===============================
-
-.. contents::
-.. sectnum::
-
-Obtaining the current py lib 
-============================
-
-Due to the nature of its innovative goals `the py lib`_ can't be 
-easily released without a certain API consistency.  Nevertheless, 
-the API is pretty stable in many respects and very 
-well tested.  So we invite you to participate and 
-use it - especially if you share `the frustrations with
-current python package development`_. 
-
-.. _`the py lib`: index.html 
-
-getting it via subversion 
--------------------------
-
-Checkout the py lib distribution tree with subversion, e.g. use:: 
-
-    svn co http://codespeak.net/svn/py/dist py-dist 
-
-to checkout the code, documentation, tool and example tree 
-into a ``py-dist`` checkout directory.  Your naming desire may vary
-for your local checkout directory. 
-
-If you experience problems with the subversion checkout e.g. 
-because you have a http-proxy in between that doesn't proxy 
-DAV requests you can try to use "codespeak.net:8080" instead 
-of just "codespeak.net".  Alternatively, you may tweak 
-your local subversion installation. 
-
-setting it up
--------------
-
-You need to put the checkout-directory into your ``PYTHONPATH``
-and you want to have the ``py-dist/py/bin/py.test`` script in 
-your system path, which lets you execute test files and directories.  
-
-There already is a convenient way for Bash/Shell based systems
-to setup the ``PYTHONPATH`` as well as the shell ``PATH``, insert:: 
-
-    eval `python ~/path/to/py-dist/py/env.py`
-
-into your ``.bash_profile``.  Of course, you need to
-specify your own checkout-directory. 
-
-If you know of a good developer-style way of doing the
-equivalent on win32 (non-cygwin) environments, tell us_. 
-
-And no, we don't yet provide a distutils-install until 
-we have settled on a convenient way to upgrade seamlessly 
-via an `svn up` while at the same time allowing 
-installs/upgrades via the distutils `setup.py` way.   
-Our `releasescheme document`_ holds some preliminary 
-planning on how future releaes of the py lib will 
-look like. 
-
-.. _`releasescheme document`: releasescheme.html
-
-upgrading it 
-------------
-
-Well, easy. Go to your checkout directory and issue:: 
-
-    svn up 
-
-have fun and `get an account`_ :-) 
-
-
-Participating in development 
-============================
-
-The py-dev and py-svn mailing lists 
------------------------------------ 
-
-If you feel the desire to help tackle bugs and fixes, 
-or support resolution of some `frustrations`_ or to
-just lurk in then please subscribe to one or both 
-of our mailinglists: 
-
-    `py-dev developers list`_ 
-
-and our  
-
-    `py-svn general commit mailing list`_ 
-
-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 
-.. _future: future/future.html 
-
-.. _`get an account`:  
-
-get an account on codespeak  
---------------------------- 
-
-codespeak_ is employing a pretty liberal committing scheme.  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 
-you are new to the python developer community you may still get one if 
-you want to improve things and can be expected to honour the 
-style of coding and communication. 
-
-.. _`coding style`: coding-style.html 
-.. _`frustrations`: 
-.. _`the frustrations with current python package development`: why_py.html#frustrations
-.. _us: http://codespeak.net/mailman/listinfo/py-dev
-.. _codespeak: http://codespeak.net/
-.. _`py-dev developers list`: http://codespeak.net/mailman/listinfo/py-dev 
-.. _`py-svn general commit mailing list`: http://codespeak.net/mailman/listinfo/py-svn 

py/doc/index.txt

@@ -1,13 +1,25 @@
-py.test and the py lib - documentation 
+py lib documentation 
----------------------------------------- 
+=================================================
+
+`Download and Installation`_ 
+
+Main tools and API 
+----------------------
 
 `py.test`_ introduces to the **py.test** testing utility
 
-`py.execnet`_ an innovative way to distribute programs across the net (not stable on win32 yet) 
+`py.execnet`_ distribute programs across the net 
 
-`py.magic.greenlet`_:  Lightweight in-process concurrent programming (aka Stackless)
+`py.magic.greenlet`_: micro-threads (lightweight in-process concurrent programming)
 
-`py.path`_: Path and Filesystem access and manipulation for local and svn based trees
+`py.path`_: local and subversion Path and Filesystem access
+
+`py lib scripts`_ describe the scripts contained in the ``py/bin`` directory. 
+
+`apigen`_: a new way to generate rich Python API documentation
+
+support functionality 
+---------------------------------
 
 `py.code`_: High-level access/manipulation of Python code and traceback objects. 
 
@@ -17,23 +29,20 @@ py.test and the py lib - documentation
 
 `py.log`_ an alpha document about the ad-hoc logging facilities 
 
-`py lib scripts`_ describe the scripts contained in the ``py/bin`` directory. 
+`miscellaneous features`_ describes some small but nice py lib features 
 
-`miscellaneous features`_ describes some more py lib features 
+Background and Motivation information 
+-------------------------------------------
 
 `future`_ handles development visions and plans for the near future. 
 
 `why what how py?`_, describing motivation and background of the py lib 
   
-Note that some parts of these texts refer to future development and
+.. _`download and installation`: download.txt
-do not reflect the current state.  **Welcome to documentation and 
-test driven development** :-)
-
-
-.. _`getting started`: getting-started.html 
 .. _`py-dev at codespeak net`: http://codespeak.net/mailman/listinfo/py-dev 
 .. _`py.execnet`: execnet.html 
 .. _`py.magic.greenlet`: greenlet.html 
+.. _`apigen`: apigen.html 
 .. _`py.log`: log.html
 .. _`py.io`: io.html
 .. _`py.path`: path.html
@@ -43,6 +52,5 @@ test driven development** :-)
 .. _`py.xml`: xml.html 
 .. _`Why What how py?`: why_py.html 
 .. _`future`: future/future.html 
-.. _`getting started`: getting-started.html 
 .. _`miscellaneous features`: misc.html 
 

py/doc/releasescheme.txt

@@ -1,113 +0,0 @@
-
-py subversion directory structure
-=================================
-
-The directory release layout of the repository is
-going to follow this scheme:: 
-
-    svn/py/dist             # latest stable code base (may or may not be a release) 
-    svn/py/release/X.Y.Z    # tagged releases  
-    svn/py/branch/X.Y       # contains release branch development
-    svn/py/trunk            # head development 
-
-Scenario "no svn and just let me play, please" 
-==============================================
-
-If you don't have a subversion client you can download 
-specific versions by going to 
-
-    http://codespeak.net/download/py 
-
-and pick a suitable archive file. You need to 
-unpack it and may want to run `setup.py` to install 
-it in a system-wide manner. 
-
-Installation Scenario "svn + stay close to released versions" 
-------------------------------------------------------------- 
-
-If you have a subversion client (you can easily install
-one, look at PyPy's `svn help document`_) it is recommended that you choose the following 
-method to install, irrespective if you want to install 
-things via distutils.   Start by issueing the following 
-shell command (or a graphical equivalent):: 
-
-    svn co http://codespeak.net/svn/py/dist py-dist
-
-Now we want to make sure that the `py-dist/py/bin` directory 
-gets on your shell search path in order to have "py.test" 
-directly available.  You basically have two choices: 
-
-1) include in your local shell environment startup the equivalent 
-   of ``eval `python .../py-dist/py/env.py```.  
-   XXX describe this in more detail (rip out from `getting started`_). 
-
-2) go to the `py-dist` directory and run `python setup.py install`. 
-
-.. _`getting started`: getting-started.html 
-.. _`svn help document`: http://codespeak.net/pypy/index.cgi?doc/getting_started.html#subversion
-
-If you later want to upgrade your version of the py lib
-to the newest release you simply issue:: 
-
-    svn up
-
-or to switch to the development trunk via:: 
-
-    svn switch http://codespeak.net/svn/py/trunk 
-
-or to a specific version via:: 
-
-    svn switch http://codespeak.net/svn/py/tag/py-X.Y.Z 
-
-or to a specific release branch:: 
-
-    svn switch http://codespeak.net/svn/py/branch/py-X.Y 
-
-If you choose the option No. 2) above you have to repeat 
-the distutils install after each checkout/switch. 
-
-.. _`svn-external scenario`: 
-
-
-Installation Scenario "svn + include py lib as an external" 
-===========================================================
-
-OK, so you want to have the py lib supporting your 
-application and are using subversion?  Great because
-things are quite easy and flexible for this scenario. 
-
-Tying the py lib into your subversion controled project
--------------------------------------------------------
-
-On the `DIRECTORY` which contains your root package issue:: 
-
-    svn pe 'svn:externals' DIRECTORY 
-
-and add the following line to your (possibly empty) list 
-of svn-externals:: 
-
-    py http://codespeak.net/svn/py/dist 
-
-This will make your projcet follow the most recent 
-release of the py lib. (please substitute `dist` for `trunk`
-if you want to follow py lib development, this will let 
-you catch interaction problems early on ...). 
-If you now issue an `svn up` on your `DIRECTORY` you 
-will retrieve the external into your application. 
-
-If you want to follow a minor release branch seamlessly
-then use the following line:: 
-
-    py http://codespeak.net/svn/py/branch/py-X.Y 
-
-where `X.Y` indicate the branch you want to follow. 
-
-If you want to use a very fixed version of the py lib
-you can tie to a specific release::  
-
-    py http://codespeak.net/svn/py/tag/py-X.Y.Z 
-
-Integrating the py lib into your distribution
-----------------------------------------------
-
-XXX 

py/doc/test.txt

@@ -14,11 +14,12 @@ also document describing the `implementation and the extending of py.test`_.
 starting point: ``py.test`` command line tool 
 =============================================
 
-First, see `getting started`_ for how to install the 'py.test' tool 
+We presume you have done an installation as per the
-on your system.
+download_ page after which you should be able to execute the
+'py.test' tool from a command line shell. 
 
 ``py.test`` is the command line tool to run tests. You can supply it
-with any Python module by passing it as an argument::
+with a Python test file (or directory) by passing it as an argument::
 
   py.test test_sample.py
 
@@ -32,11 +33,9 @@ This means you can write tests without any boilerplate::
     def test_answer():
         assert 42 == 43 
 
-As you can see, you can have test functions as well as test
+You may have test functions and test methods, there is no
-methods. This in contrast to the Python standard library's
+need to subclass or to put tests into a class. 
-``unittest.py``.
+You can also use ``py.test`` to run all tests in a directory structure by
-
-You can use ``py.test`` to run all tests in a directory structure by
 invoking it without any arguments::
 
   py.test
@@ -46,9 +45,7 @@ start with ``test_`` or ends with ``_test`` from the directory and any
 subdirectories, starting with the current directory, and run them. Each 
 Python test module is inspected for test methods starting with ``test_``. 
 
-.. _`getting started`: getting-started.html
+.. _download: download.html
-
-
 .. _features: 
 
 Basic Features of ``py.test`` 

py/doc/why_py.txt

@@ -127,7 +127,7 @@ release policies:
   completly change the implementation but the public API 
   tests will continue to run. 
 
-- No **tested feature** of the exported `py API`_ is to vanish
+- No **tested feature** of the exported py API is to vanish
   across minor releases until it is marked deprecated.  
 
   For example, pure API tests of a future version 1.0 are to
@@ -269,7 +269,6 @@ to walk up or boot up a windows machine :-)
 .. _`envisioned import/export system`: future/future.html#importexport
 .. _future: future/future.html
 .. _`py.test tool and library`: test.html
-.. _`py API`: api.html 
 .. _`great work that Fred L. Drake, Jr. is doing`: http://www.python.org/doc/2.3.4/lib/lib.html
 
 --