From add44ae821b25bd33467210b08fedd48b8409492 Mon Sep 17 00:00:00 2001 From: Jonathan Ballet Date: Sat, 16 Jul 2011 14:39:36 +0900 Subject: Convert introduction and installation doc from Latex to Sphinx --- doc/index.rst | 6 +++ doc/install.rst | 70 +++++++++++++++++++++++++++++++ doc/introduction.rst | 17 ++++++++ old-doc/pyOpenSSL.tex | 111 -------------------------------------------------- 4 files changed, 93 insertions(+), 111 deletions(-) create mode 100644 doc/install.rst create mode 100644 doc/introduction.rst 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 `_) +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} -- cgit v1.2.1