Merge branch 'clean-text-files'

INSTALL

@@ -1,103 +1,4 @@
-Compiling and installing psycopg
+Installation instructions are included in the docs.
-********************************
-
-** Important note: if you plan to use psycopg2 in a multithreaded application,
-   make sure that your libpq has been compiled with the --with-thread-safety
-   option. psycopg2 will work correctly even with a non-thread-safe libpq but
-   libpq will leak memory.
-
-psycopg2 uses distutils for its build process, so most of the process is
-executed by the setup.py script.  Before building psycopg look at
-setup.cfg file and change any settings to follow your system (or taste);
-then:
-
-    python setup.py build
-
-to build in the local directory; and:
-
-    python setup.py install
-
-to install system-wide.
-
-
-Common errors and build problems
-================================
-
-One of the most common errors is trying to build psycopg without the right
-development headers for PostgreSQL, Python or both. If you get errors, look
-for the following messages and then take the appropriate action:
-
-libpq-fe.h: No such file or directory
-  PostgreSQL headers are not properly installed on your system or are
-  installed in a non default path. First make sure they are installed, then
-  check setup.cfg and make sure pg_config points to a valid pg_config
-  executable. If you don't have a working pg_config try to play with the
-  include_dirs variable (and note that a working pg_config is better.)
-
-
-Running the test suite
-======================
-
-The included Makefile allows to run all the tests included in the
-distribution. Just use:
-
-    make
-    make check
-
-The tests are run against a database called psycopg2_test on unix socket
-and standard port. You can configure a different database to run the test
-by setting the environment variables:
-
-- PSYCOPG2_TESTDB
-- PSYCOPG2_TESTDB_HOST
-- PSYCOPG2_TESTDB_PORT
-- PSYCOPG2_TESTDB_USER
-
-The database should be created before running the tests.
-
-The standard Python unittest is used to run the tests. But if unittest2 is
-found it will be used instead, with the result of having more informations
-about skipped tests.
-
-
-Building the documentation
-==========================
-
-In order to build the documentation included in the distribution, use
-
-    make env
-    make docs
-
-The first command will install all the dependencies (Sphinx, Docutils) in
-an 'env' directory in the project tree. The second command will build both
-the html format (in the 'doc/html' directory) and in plain text
-(doc/psycopg2.txt)
-
-
-Using setuptools and EasyInstall
-================================
-
-If setuptools are installed on your system you can easily create an egg for
-psycopg and install it. Download the source distribution (if you're reading
-this file you probably already have) and then edit setup.cfg to your taste
-and build from the source distribution top-level directory using:
-
-    easy_install .
-
-
-Compiling under Windows with mingw32
-====================================
-
-You can compile psycopg under Windows platform with mingw32
-(http://www.mingw.org/) compiler. MinGW is also shipped with IDEs such as
-Dev-C++ (http://www.bloodshed.net/devcpp.html) and Code::Blocks
-(http://www.codeblocks.org). gcc binaries should be in your PATH.
-
-You need a PostgreSQL with include and library files installed. At least v8.0
-is required.
-
-First you need to create a libpython2X.a as described in
-http://starship.python.net/crew/kernr/mingw32/Notes.html. Then run:
-
-    python setup.py build_ext --compiler=mingw32 install
 
+Please check the 'doc/src/install.rst' file or online at
+<http://initd.org/psycopg/docs/install.html>.

MANIFEST.in

@@ -2,9 +2,9 @@ recursive-include psycopg *.c *.h *.manifest
 recursive-include lib *.py
 recursive-include tests *.py
 recursive-include examples *.py somehackers.jpg whereareyou.jpg
-recursive-include doc README HACKING SUCCESS COPYING.LESSER pep-0249.txt
+recursive-include doc README SUCCESS COPYING.LESSER pep-0249.txt
 recursive-include doc/src *.rst *.py *.css Makefile
 recursive-include scripts *.py *.sh
 include scripts/maketypes.sh scripts/buildtypes.py
-include AUTHORS README INSTALL LICENSE NEWS
+include AUTHORS README.rst INSTALL LICENSE NEWS
 include PKG-INFO MANIFEST.in MANIFEST setup.py setup.cfg Makefile

README

@@ -1,38 +0,0 @@
-psycopg2 - Python-PostgreSQL Database Adapter
-********************************************
-
-psycopg2 is a PostgreSQL database adapter for the Python programming
-language.  psycopg2 was written with the aim of being very small and fast,
-and stable as a rock.
-
-psycopg2 is different from the other database adapter because it was
-designed for heavily multi-threaded applications that create and destroy
-lots of cursors and make a conspicuous number of concurrent INSERTs or
-UPDATEs. psycopg2 also provides full asynchronous operations and support
-for coroutine libraries.
-
-psycopg2 can compile and run on Linux, FreeBSD, Solaris, MacOS X and
-Windows architecture. It supports Python versions from 2.4 onwards and
-PostgreSQL versions from 7.4 onwards.
-
-psycopg2 is free software ("free as in freedom" but I like beer too.)
-It is licensed under the GNU Lesser General Public License, version 3 or
-later plus an exception to allow OpenSSL (libpq) linking; see LICENSE for
-more details.
-
-Documentation
--------------
-
-Start by reading the INSTALL file. More information about psycopg2 extensions
-to the DBAPI-2.0 is available in the files located in the doc/ direcory.
-Example code can be found in the examples/ directory. If you make any changes
-to the code make sure to run the unit tests localed in tests/.
-
-Online documentation can be found at: http://initd.org/psycopg/
-
-If you stumble upon any bugs, please tell us at: http://psycopg.lighthouseapp.com/
-
-Contributors
-------------
-
-For a list of contributors to the project, see the AUTHORS file.

README.rst

@@ -0,0 +1,44 @@
+psycopg2 - Python-PostgreSQL Database Adapter
+=============================================
+
+Psycopg is the most popular PostgreSQL database adapter for the Python
+programming language.  Its main features are the complete implementation of
+the Python DB API 2.0 specification and the thread safety (several threads can
+share the same connection).  It was designed for heavily multi-threaded
+applications that create and destroy lots of cursors and make a large number
+of concurrent "INSERT"s or "UPDATE"s.
+
+Psycopg 2 is mostly implemented in C as a libpq wrapper, resulting in being
+both efficient and secure.  It features client-side and server-side cursors,
+asynchronous communication and notifications, "COPY TO/COPY FROM" support.
+Many Python types are supported out-of-the-box and adapted to matching
+PostgreSQL data types; adaptation can be extended and customized thanks to a
+flexible objects adaptation system.
+
+Psycopg 2 is both Unicode and Python 3 friendly.
+
+
+Documentation
+-------------
+
+Documentation is included in the 'doc' directory and is `available online`__.
+
+.. __: http://initd.org/psycopg/docs/
+
+
+Installation
+------------
+
+If all the dependencies are met (i.e. you have the Python and libpq
+development packages installed in your system) the standard::
+
+    python setup.py build
+    sudo python setup.py install
+
+should work no problem.  In case you have any problem check the 'install' and
+the 'faq' documents in the docs or online.
+
+For any other resource (source code repository, bug tracker, mailing list)
+please check the `project homepage`__.
+
+.. __: http://initd.org/psycopg/

doc/HACKING

@@ -1,43 +0,0 @@
-General information
-*******************
-
-Some help to people wanting to hack on psycopg. First of all, note that
-*every* function in the psycopg module source code is prefixed by one of the
-following words:
-
-    psyco is used for function directly callable from python (i.e., functions
-        in the psycopg module itself.) the only notable exception is the
-        source code for the module itself, that uses "psyco" even for C-only
-        functions.
-
-    conn is used for functions related to connection objects.
-
-    curs is used for functions related to cursor objects.
-
-    typecast is used for typecasters and utility function related to
-        typecaster creation and registration.
-
-Pythonic definition of types and functions available from python are defined
-in *_type.c files. Internal functions, callable only from C are located in
-*_int.c files and extensions to the DBAPI can be found in the *_ext.c files.
-
-
-Patches
-*******
-
-If you submit a patch, please send a diff generated with the "-u" switch.
-Also note that I don't like that much cosmetic changes (like renaming
-already existing variables) and I will rewrap the patch to 78 columns
-anyway, so it is much better if you do that beforehand.
-
-
-The type system
-***************
-
-Simple types, like integers and strings, are converted to python base types
-(the conversion functions are in typecast_base.c). Complex types are
-converted to ad-hoc types, defined in the typeobj_*.{c,h} files. The
-conversion function are in the other typecast_*.c files. typecast.c defines
-the basic utility functions (available through the psycopg module) used when
-defining new typecasters from C and python.
-

doc/src/install.rst

@@ -205,6 +205,33 @@ supported.
 
 
 
+.. index::
+    single: tests
+
+.. _test-suite:
+
+Running the test suite
+^^^^^^^^^^^^^^^^^^^^^^
+
+The included ``Makefile`` allows to run all the tests included in the
+distribution. Just run::
+
+    make
+    make check
+
+The tests run against a database called ``psycopg2_test`` on UNIX socket and
+the standard port. You can configure a different database to run the test by
+setting the environment variables:
+
+- :envvar:`PSYCOPG2_TESTDB`
+- :envvar:`PSYCOPG2_TESTDB_HOST`
+- :envvar:`PSYCOPG2_TESTDB_PORT`
+- :envvar:`PSYCOPG2_TESTDB_USER`
+
+The database should already exist before running the tests.
+
+
+
 .. index::
     single: debug
     single: PSYCOPG_DEBUG
@@ -225,13 +252,13 @@ order to create a debug package:
 
 - :ref:`Compile and install <source-package>` the package.
 
-- Set the :envvar:`PSYCOPG_DEBUG` variable::
+- Set the :envvar:`PSYCOPG_DEBUG` environment variable::
 
     $ export PSYCOPG_DEBUG=1
 
 - Run your program (making sure that the `!psycopg2` package imported is the
   one you just compiled and not e.g. the system one): you will have a copious
-  stream of informations printed on stdout.
+  stream of informations printed on stderr.
 
 .. __: http://initd.org/psycopg/download/
 

psycopg2.cproj

@@ -44,10 +44,9 @@
     <None Include="INSTALL" />
     <None Include="LICENSE" />
     <None Include="MANIFEST.in" />
-    <None Include="README" />
+    <None Include="README.rst" />
     <None Include="setup.cfg" />
     <None Include="setup.py" />
-    <None Include="doc\HACKING" />
     <None Include="doc\SUCCESS" />
     <None Include="examples\binary.py" />
     <None Include="examples\copy_from.py" />