merge install and basic usage into getting-started.txt

add an assert1.txt

--HG--
branch : trunk

doc/apiref.txt

@@ -1,10 +1,13 @@
 
+.. _apiref:
+
 py.test reference documentation
 ================================================
 
 .. toctree::
    :maxdepth: 2
-  
+ 
+   assert.txt 
    funcargs.txt
    xunit_setup.txt
    capture.txt

doc/assert.txt

@@ -0,0 +1,135 @@
+
+Writing easy assertions in tests
+============================================
+
+assert with the ``assert`` statement
+---------------------------------------------------------
+
+``py.test`` allows to use the standard python ``assert`` for verifying
+expectations and values in Python tests.  For example, you can write the
+following in your tests::
+
+    # content of test_assert1.py
+    def f():
+        return 3
+
+    def test_function():
+        assert f() == 4
+
+to state that your object has a certain ``attribute``. In case this
+assertion fails you will see the value of ``x``::
+
+    $ py.test test_assert1.py
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0
+    test path 1: test_assert1.py
+    
+    test_assert1.py F
+    
+    ================================= FAILURES =================================
+    ______________________________ test_function _______________________________
+    
+        def test_function():
+    >       assert f() == 4
+    E       assert 3 == 4
+    E        +  where 3 = f()
+    
+    test_assert1.py:5: AssertionError
+    ========================= 1 failed in 0.02 seconds =========================
+
+Reporting details about the failing assertion is achieved by re-evaluating
+the assert expression and recording intermediate values.
+
+Note: If evaluating the assert expression has side effects you may get a
+warning that the intermediate values could not be determined safely.  A 
+common example for this issue is reading from a file and comparing in one
+line::
+
+        assert f.read() != '...'
+
+This might fail but when re-interpretation comes along it might pass.
+You can rewrite this (and any other expression with side effects) easily, though:
+
+        content = f.read()
+        assert content != '...'
+
+assertions about expected exceptions
+------------------------------------------
+
+In order to write assertions about raised exceptions, you can use
+``py.test.raises`` as a context manager like this::
+
+    with py.test.raises(ZeroDivisionError):
+        1 / 0
+
+and if you need to have access to the actual exception info you may use::
+
+    with py.test.raises(RuntimeError) as excinfo:
+        def f():
+            f()
+        f()
+
+    # do checks related to excinfo.type, excinfo.value, excinfo.traceback
+
+If you want to write test code that works on Python2.4 as well,
+you may also use two other ways to test for an expected exception::
+
+    py.test.raises(ExpectedException, func, *args, **kwargs)
+    py.test.raises(ExpectedException, "func(*args, **kwargs)")
+
+both of which execute the specified function with args and kwargs and
+asserts that the given ``ExpectedException`` is raised.  The reporter will
+provide you with helpful output in case of failures such as *no
+exception* or *wrong exception*.
+
+Making use of context-sensitive comparisons
+-------------------------------------------------
+
+.. versionadded:: 2.0
+
+py.test has rich support for providing context-sensitive informations
+when it encounters comparisons.  For example::
+
+    # content of test_assert2.py
+
+    def test_set_comparison():
+        set1 = set("1308")
+        set2 = set("8035")
+        assert set1 == set2
+
+if you run this module::
+
+    $ py.test test_assert2.py
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0
+    test path 1: test_assert2.py
+    
+    test_assert2.py F
+    
+    ================================= FAILURES =================================
+    ___________________________ test_set_comparison ____________________________
+    
+        def test_set_comparison():
+            set1 = set("1308")
+            set2 = set("8035")
+    >       assert set1 == set2
+    E       assert set(['0', '1', '3', '8']) == set(['0', '3', '5', '8'])
+    E         Extra items in the left set:
+    E         '1'
+    E         Extra items in the right set:
+    E         '5'
+    
+    test_assert2.py:5: AssertionError
+    ========================= 1 failed in 0.02 seconds =========================
+
+Special comparisons are done for a number of cases:
+
+* comparing long strings: a context diff is shown
+* comparing long sequences: first failing indices
+* comparing dicts: different entries
+
+.. 
+    Defining your own comparison
+    ----------------------------------------------
+
+

doc/cmdline.txt

@@ -1,4 +1,6 @@
 
+.. _cmdline:
+
 Using the interactive command line
 ===============================================
 

doc/example/x.txt

@@ -105,60 +105,6 @@ that do not fail.
 
 .. _captured: plugin/capture.html
 
-assert with the ``assert`` statement
-+++++++++++++++++++++++++++++++++++++++++++++
-
-``py.test`` allows to use the standard python
-``assert statement`` for verifying expectations
-and values in Python tests.  For example, you can
-write the following in your tests::
-
-     assert hasattr(x, 'attribute')
-
-to state that your object has a certain ``attribute``. In case this
-assertion fails you will see the value of ``x``.  Intermediate
-values are computed by executing the assert expression a second time.
-If you execute code with side effects, e.g. read from a file like this::
-
-        assert f.read() != '...'
-
-then you may get a warning from pytest if that assertions
-first failed and then succeeded.
-
-asserting expected exceptions
-+++++++++++++++++++++++++++++++++++++++
-
-In order to write assertions about exceptions, you can use
-``py.test.raises`` as a context manager like this:
-
-.. sourcecode:: python
-
-    with py.test.raises(ZeroDivisionError):
-        1 / 0
-
-and if you need to have access to the actual exception info you may use:
-
-.. sourcecode:: python
-
-    with py.test.raises(RuntimeError) as excinfo:
-        def f():
-            f()
-        f()
-
-    # do checks related to excinfo.type, excinfo.value, excinfo.traceback
-
-If you want to write test code that works on Python2.4 as well,
-you may also use two other ways to test for an expected exception:
-
-.. sourcecode:: python
-
-    py.test.raises(ExpectedException, func, *args, **kwargs)
-    py.test.raises(ExpectedException, "func(*args, **kwargs)")
-
-both of which execute the specified function with args and kwargs and
-asserts that the given ``ExpectedException`` is raised.  The reporter will
-provide you with helpful output in case of failures such as *no
-exception* or *wrong exception*.
 
 information-rich tracebacks, PDB introspection
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++

doc/examples.txt

@@ -1,4 +1,6 @@
 
+.. _examples:
+
 Usages and Examples
 ===========================================
 

doc/getting-started.txt

@@ -1,17 +1,28 @@
-.. _`setuptools installation`: http://pypi.python.org/pypi/setuptools
+Installation and Getting Started
+===================================
 
+.. _`easy_install`:
 
-Basic usage
+Installation using easy_install
-==================
+----------------------------------------
 
-We assume you have done an :ref:`install` like this::
+**PyPI distribution name**: pytest_.  **repository**: https://bitbucket.org/hpk42/pytest
 
-    easy_install -U pytest # or
+**Compatibility**: Python 2.4-3.2, Jython, PyPy on Unix/Posix and Windows
-    pip install -U pytest
 
-Ensure that this installed the ``py.test`` script::
+You need to have setuptools_ or Distribute_ to install or upgrade ``py.test``::
 
-    py.test --version
+    easy_install -U pytest
+
+Note that setuptools works for Python2 interpreters and
+**Distribute works for both Python3 and Python2** and fixes some issues
+on Windows.  You may also use pip_ for installation on Python2 interpreters.
+
+To check your installation works type::
+
+    $ py.test --version
+
+If you get an error, checkout :ref:`installation issues`.
 
 
 Writing a first test
@@ -56,3 +67,14 @@ A few notes on this little test invocation:
 
 .. _`assert statement`: http://docs.python.org/reference/simple_stmts.html#the-assert-statement
 
+
+where to go from here
+-------------------------------------
+
+Here are a few suggestions where to go next:
+
+* :ref:`cmdline` for command line invocation examples
+* :ref:`good practises` for virtualenv, test layout, genscript support
+* :ref:`apiref` for documentation and examples on writing Python tests
+* :ref:`examples` for more complex examples
+

doc/goodpractises.txt

@@ -1,4 +1,6 @@
 
+.. _`good practises`:
+
 Good Practises
 =================================================
 
@@ -18,6 +20,17 @@ reproducible and reliable test environment.
 
 .. _standalone:
 
+
+Choosing a test layout
+----------------------------
+
+py.test supports common test layouts.
+
+XXX
+
+
+
+
 Generating a py.test standalone Script
 -------------------------------------------
 

doc/install.txt

@@ -1,33 +0,0 @@
-
-installing py.test
-===================================================
-
-**PyPI name**: pytest_
-
-**hg repository**: https://bitbucket.org/hpk42/pytest
-
-**Compatibility**: Python 2.4-3.2, Jython, PyPy on Unix/Posix and Windows
-
-.. _`easy_install`:
-
-Installation using easy_install
-----------------------------------------
-
-If you have setuptools_ or Distribute_ type::
-
-    easy_install -U pytest
-
-to install the latest release of ``py.test``.  The ``-U`` switch
-triggers an upgrade if you already have an older version installed.
-Note that setuptools works ok with Python2 interpreters while **Distribute
-works with Python3 and Python2** and also avoids some issues on Windows.
-
-You should now be able to type::
-
-    $ py.test --version
-
-Refer to :ref:`installation issues` if you have issues.
-
-.. include:: links.inc
-
-

doc/links.inc

@@ -11,4 +11,6 @@
 .. _mercurial: http://mercurial.selenic.com/wiki/
 .. _`setuptools`: http://pypi.python.org/pypi/setuptools
 .. _`distribute`: http://pypi.python.org/pypi/distribute
+.. _`pip`: http://pypi.python.org/pypi/pip
+.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
 .. _hudson: http://hudson-ci.org/

doc/overview.txt

@@ -6,8 +6,7 @@ Overview and Introduction
    :maxdepth: 2
 
    features.txt
-   install.txt
+   getting-started.txt
-   basic_usage.txt
    cmdline.txt
    goodpractises.txt
    faq.txt