[py-svn] r7048 - py/dist/doc

[hpk at codespeak.net]

Author: hpk
Date: Tue Oct 19 22:49:09 2004
New Revision: 7048

Modified:
   py/dist/doc/coding-style.txt
   py/dist/doc/getting_started.txt
   py/dist/doc/index.txt
Log:
- improving getting started and other documentation 

- put some more emphasize on documentation & test driven 
  development, literally. 



Modified: py/dist/doc/coding-style.txt
==============================================================================
--- py/dist/doc/coding-style.txt	(original)
+++ py/dist/doc/coding-style.txt	Tue Oct 19 22:49:09 2004
@@ -12,7 +12,15 @@
 Style Guide for Python Code`_ which, if in doubt, serves as
 the default coding-style for the py lib. 
 
-Naming 
+Documentation and Testing 
+-------------------------
+
+- generally we want to drive and interweave coding of
+  documentation, tests and real code as much as possible. 
+  Without good documentation others may never know about
+  the latest and greatest feature.  
+
+naming 
 ------
 
 - directories, modules and namespaces are always **lowercase**
@@ -28,7 +36,7 @@
   so that tab-completion on the shell level is as easy as possible. 
 
 
-Committing
+committing
 ----------
 
 - adding features requires adding appropriate tests. 

Modified: py/dist/doc/getting_started.txt
==============================================================================
--- py/dist/doc/getting_started.txt	(original)
+++ py/dist/doc/getting_started.txt	Tue Oct 19 22:49:09 2004
@@ -4,8 +4,8 @@
 .. contents::
 .. sectnum::
 
-getting the current py lib 
-==========================
+Obtaining the current py lib 
+============================
 
 Due to the nature of its goals the py lib can't be easily 
 released without a certain API consistency.  Nevertheless, 
@@ -28,12 +28,12 @@
 setting it up
 -------------
 
-You need to put the checkout-directory into your PYTHONPATH
+You need to put the checkout-directory into your ``PYTHONPATH``
 and you want to have the ``dist-py/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:: 
+to setup the ``PYTHONPATH`` as well as the shell ``PATH``, insert:: 
 
     eval `python ~/path/to/dist-py/dist/py/env.py`
 
@@ -46,31 +46,69 @@
 And no, we don't provide a distutils-install currently, 
 because we really want have the py lib installable 
 on multiple python versions, want to have automated
-upgrades ...
+upgrades ...  
 
 upgrading it 
 ------------
 
-Well, simple. Go to your checkout and issue:: 
+Well, easy. Go to your checkout directory and issue:: 
 
     svn up 
 
-:-) 
+have fun and `get an account`_ :-) 
 
 
 Participating in development 
 ============================
 
+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://www.zope3.org
+.. _twisted: http://www.twistedmatrix.org 
+.. _`get an account`: 
+.. _future: future.html 
+
+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`_ then 
-please subscribe to our mailinglist: 
+or support resolution of some `frustrations`_ or to
+just lurk in then please subscribe to one or both 
+of our mailinglists: 
+
+    `the py lib's py-dev developers list`_ 
+
+and 
+
+    `the py lib's py-svn general commit mailing list`_ 
 
-    http://codespeak.net/mailman/listinfo/py-dev 
+get an account on codespeak  
+--------------------------- 
 
-or start communicating by submitting improved code 
-if you already have an account on codespeak_. 
+codespeak_ is generally deploying a very 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/
+.. _`the py lib's developers list`: http://codespeak.net/mailman/listinfo/py-dev 
+.. _`the py lib's general commit mailing list`: http://codespeak.net/mailman/listinfo/py-svn 

Modified: py/dist/doc/index.txt
==============================================================================
--- py/dist/doc/index.txt	(original)
+++ py/dist/doc/index.txt	Tue Oct 19 22:49:09 2004
@@ -20,8 +20,9 @@
    `future`_ handles development visions and plans for the near future. 
   
 Note that some parts of these texts refer to future development and
-do not exactly reflect the current state.  Welcome to
-documentation & test driven development :-) 
+do not exactly reflect the current state.  
+
+**Welcome to documentation and test driven development** :-)
 
 There is some preliminary documentation for `getting started`_