[svn r38455] various merging of startup documentation

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

--HG--
branch : trunk
This commit is contained in:
hpk 2007-02-11 14:26:03 +01:00
parent edfa8f99d5
commit 40c8b10040
11 changed files with 217 additions and 297 deletions

View File

@ -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
-------------------------------------

View File

@ -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

View File

@ -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
.. _`development mailing list`: http://codespeak.net/mailman/listinfo/py-dev
If you see bugs and/or can provide patches, please
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/

113
py/doc/download.txt Normal file
View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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
do not reflect the current state. **Welcome to documentation and
test driven development** :-)
.. _`getting started`: getting-started.html
.. _`download and installation`: download.txt
.. _`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

View File

@ -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

View File

@ -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
on your system.
We presume you have done an installation as per the
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
methods. This in contrast to the Python standard library's
``unittest.py``.
You can use ``py.test`` to run all tests in a directory structure by
You may have test functions and test methods, there is no
need to subclass or to put tests into a class.
You can also 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``

View File

@ -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
--