Convert introduction and installation doc from Latex to Sphinx

4 files changed, 93 insertions, 111 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.
diff --git a/old-doc/pyOpenSSL.tex b/old-doc/pyOpenSSL.tex
index 6a49748..8278c5e 100644
--- a/old-doc/pyOpenSSL.tex
+++ b/old-doc/pyOpenSSL.tex
@@ -1,114 +1,3 @@
-\documentclass{howto}
-
-\title{Python OpenSSL Manual}
-
-\release{0.12}
-
-\author{Jean-Paul Calderone}
-\authoraddress{\email{exarkun@twistedmatrix.com}}
-
-\usepackage[english]{babel}
-\usepackage[T1]{fontenc}
-
-\begin{document}
-
-\maketitle
-
-\begin{abstract}
-\noindent
-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.
-\end{abstract}
-
-\tableofcontents
-
-
-\section{Introduction \label{intro}}
-
-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\footnote{See \url{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.
-
-\section{Building and Installing \label{building}}
-
-These instructions can also be found in the file \verb|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.
-
-\subsection{Building the Module on a Unix System \label{building-unix}}
-
-pyOpenSSL uses distutils, so there really shouldn't be any problems. To build
-the library:
-\begin{verbatim}
-python setup.py build
-\end{verbatim}
-
-If your OpenSSL header files aren't in \verb|/usr/include|, you may need to
-supply the \verb|-I| flag to let the setup script know where to look. The same
-goes for the libraries of course, use the \verb|-L| flag. Note that
-\verb|build| won't accept these flags, so you have to run first
-\verb|build_ext| and then \verb|build|! Example:
-\begin{verbatim}
-python setup.py build_ext -I/usr/local/ssl/include -L/usr/local/ssl/lib
-python setup.py build
-\end{verbatim}
-
-Now you should have a directory called \verb|OpenSSL| that contains e.g.
-\verb|SSL.so| and \verb|__init__.py| somewhere in the build dicrectory,
-so just:
-\begin{verbatim}
-python setup.py install
-\end{verbatim}
-
-If you, for some arcane reason, don't want the module to appear in the
-\verb|site-packages| directory, use the \verb|--prefix| option.
-
-You can, of course, do
-\begin{verbatim}
-python setup.py --help
-\end{verbatim}
-
-to find out more about how to use the script.
-
-\subsection{Building the Module on a Windows System \label{building-windows}}
-
-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 \verb|build_ext| and the \verb|build|.
-
-Building the library:
-
-\begin{verbatim}
-setup.py build_ext -I ...\openssl\inc32 -L ...\openssl\out32dll
-setup.py build
-\end{verbatim}
-
-Where \verb|...\openssl| is of course the location of your OpenSSL installation.
-
-Installation is the same as for Unix systems:
-\begin{verbatim}
-setup.py install
-\end{verbatim}
-
-And similarily, you can do
-\begin{verbatim}
-setup.py --help
-\end{verbatim}
-
-to get more information.
-
-
 \section{\module{OpenSSL} --- Python interface to OpenSSL \label{openssl}}
 
 \declaremodule{extension}{OpenSSL}