Convert introduction and installation doc from Latex to Sphinx

3 files changed, 93 insertions, 0 deletions

diff --git a/doc/index.rst b/doc/index.rst
index fd79546..c083d3d 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -6,11 +6,17 @@
 Welcome to pyOpenSSL's documentation!
 =====================================
 
+This module is a rather thin wrapper around (a subset of) the OpenSSL library.
+With thin wrapper I mean that a lot of the object methods do nothing more than
+calling a corresponding function in the OpenSSL library.
+
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
+   introduction
+   install
    api
 
 Indices and tables
diff --git a/doc/install.rst b/doc/install.rst
new file mode 100644
index 0000000..fc3c348
--- /dev/null
+++ b/doc/install.rst
@@ -0,0 +1,70 @@
+.. _building:
+
+Building and Installing
+=======================
+
+
+These instructions can also be found in the file ``INSTALL``.
+
+I have tested this on Debian Linux systems (woody and sid), Solaris 2.6 and
+2.7. Others have successfully compiled it on Windows and NT.
+
+.. _building-unix:
+
+Building the Module on a Unix System
+------------------------------------
+
+pyOpenSSL uses distutils, so there really shouldn't be any problems. To build
+the library::
+
+    python setup.py build
+
+If your OpenSSL header files aren't in ``/usr/include``, you may need to supply
+the ``-I`` flag to let the setup script know where to look. The same goes for
+the libraries of course, use the ``-L`` flag. Note that ``build`` won't accept
+these flags, so you have to run first ``build_ext`` and then ``build``!
+Example::
+
+    python setup.py build_ext -I/usr/local/ssl/include -L/usr/local/ssl/lib
+    python setup.py build
+
+Now you should have a directory called ``OpenSSL`` that contains e.g.
+``SSL.so`` and ``__init__.py`` somewhere in the build dicrectory,
+so just::
+
+    python setup.py install
+
+If you, for some arcane reason, don't want the module to appear in the
+``site-packages`` directory, use the ``--prefix`` option.
+
+You can, of course, do::
+
+    python setup.py --help
+
+to find out more about how to use the script.
+
+.. _building-windows:
+
+Building the Module on a Windows System
+---------------------------------------
+
+Big thanks to Itamar Shtull-Trauring and Oleg Orlov for their help with
+Windows build instructions.  Same as for Unix systems, we have to separate
+the ``build_ext`` and the ``build``.
+
+Building the library::
+
+    setup.py build_ext -I ...\openssl\inc32 -L ...\openssl\out32dll
+    setup.py build
+
+Where ``...\openssl`` is of course the location of your OpenSSL installation.
+
+Installation is the same as for Unix systems::
+
+    setup.py install
+
+And similarily, you can do::
+
+    setup.py --help
+
+to get more information.
diff --git a/doc/introduction.rst b/doc/introduction.rst
new file mode 100644
index 0000000..c29f80c
--- /dev/null
+++ b/doc/introduction.rst
@@ -0,0 +1,17 @@
+.. _intro:
+
+Introduction
+============
+
+The reason pyOpenSSL was created is that the SSL support in the socket module in
+Python 2.1 (the contemporary version of Python when the pyOpenSSL project was
+begun) was severely limited.  Other OpenSSL wrappers for Python at the time were
+also limited, though in different ways.  Unfortunately, Python's standard
+library SSL support has remained weak, although other packages (such as
+`M2Crypto <http://chandlerproject.org/Projects/MeTooCrypto>`_)
+have made great advances and now equal or exceed pyOpenSSL's functionality.
+
+The reason pyOpenSSL continues to be maintained is that there is a significant
+user community around it, as well as a large amount of software which depends on
+it.  It is a great benefit to many people for pyOpenSSL to continue to exist and
+advance.