Merge pull request xhtml2pdf#14 from kgrodzicki/master

Documentation and support @page template:left and @page template:right

.gitignore

@@ -19,3 +19,5 @@ testrender/output/
 *.swp
 .coverage
 htmlcov/
+xhtml2pdf.egg-info
+*.pdf

AUTHORS.rst

@@ -31,6 +31,7 @@ the maintainer should theses names be changed to something more relevant.
 * Stefan Foulis
 * Ethan Jucovy
 * Marcus Weseloh
+* Jacob Richardson
 
 Special thanks
 ==============

README.rst

@@ -1,29 +1,84 @@
-ABOUT
+*********
+xhtml2pdf
+*********
+
+HTML/CSS to PDF converter based on Python
+
+About
 =====
 
-xhtml2pdf is a html2pdf converter using the ReportLab Toolkit,
+``xhtml2pdf`` is a html2pdf converter using the ReportLab Toolkit,
 the HTML5lib and pyPdf. It supports HTML 5 and CSS 2.1 (and some of CSS 3).
 It is completely written in pure Python so it is platform independent.
 
 The main benefit of this tool that a user with Web skills like HTML and CSS
 is able to generate PDF templates very quickly without learning new
-technologies. 
+technologies.
 
-REQUIREMENTS
+Requirements
 ============
 
-- `Reportlab Toolkit 2.2+ <http://www.reportlab.org/>`_
-- `html5lib 0.11.1+ <http://code.google.com/p/html5lib/>`_
-- `pyPdf 1.11+ (optional) <http://pybrary.net/pyPdf/>`_
+#. `Reportlab Toolkit 2.2+ <http://www.reportlab.org/>`_
+#. `html5lib 0.11.1+ <http://code.google.com/p/html5lib/>`_
+#. `pyPdf 1.11+ (optional) <http://pybrary.net/pyPdf/>`_
+
+   All requirements are listed in ``requirements.txt`` file.
+
+Development environment
+=======================
+
+Python, virtualenv and dependencies
+-----------------------------------
+
+#. Install Python 2.6.x or 2.7.x. Installation steps depends on yours operating system.
+
+#. Install Pip, the python package installer::
+
+    sudo easy_install pip
+
+   For more information about ``pip`` refer to http://www.pip-installer.org/.
+
+#. I will recommend using ``virtualenv`` for development. This is great to have separate environment for
+   each project, keeping the dependencies for multiple projects separated::
+
+    sudo pip install virtualenv
+
+   For more information about ``virtualenv`` refer to http://www.virtualenv.org/
+
+#. Create virtualenv for the project. This can be inside the project directory, but cannot be under
+   version control::
+
+    virtualenv --distribute xhtml2pdfenv
 
-PYTHON INTEGRATION
+#. Activate your virtualenv::
+
+    source xhtml2pdfenv/bin/activate
+
+   Later to deactivate use::
+
+    deactivate
+
+#. Next step will be to install/upgrade dependencies from ``requirements.txt`` file::
+
+    pip install -r requirements.txt
+
+#. Run tests to check you configuration::
+
+    nosetests --with-coverage
+
+   You should have log with success status::
+
+    Ran 35 tests in 0.322s
+
+    OK
+
+Python integration
 ==================
 
 Some simple demos of how to integrate xhtml2pdf into
 a Python program may be found here: test/simple.py
 
-
-CONTRIBUTING
+Contributing
 ============
 
 Development for this software happend on github, and the main fork is
@@ -33,32 +88,30 @@ Contributions are welcome in any format, but using github's pull request
 system is very highly preferred since it makes review and integration
 much easier.
 
-RUNNING TESTS
+Running tests
 =============
 
 Two different test suites are available to assert xhtml2pdf works reliably:
 
-1. Unit tests. The unit testing framework is currently minimal, but is being
+#. Unit tests. The unit testing framework is currently minimal, but is being
    improved on a daily basis (contributions welcome). They should run in the
    expected way for Python's unittest module, i.e.::
 
         nosetests --with-coverage (or your personal favorite)
 
+#. Functional tests. Thanks to mawe42's super cool work, a full functional
+   test suite lives in testrender/.
 
-2. Functional tests. Thanks to mawe42's super cool work, a full functional
-   test suite lives in rendertests/.
-
-
-CONTACT
+Contact
 =======
 
-IRC: #xhtml2pdf on freenode
-Mailing list: xhtml2pdf@googlegroups.com
-Google group: http://groups.google.com/group/xhtml2pdf
+* IRC: #xhtml2pdf on freenode
+* Mailing list: xhtml2pdf@googlegroups.com
+* Google group: http://groups.google.com/group/xhtml2pdf
 
 Maintainer: Chris Glass <tribaal@gmail.com>
 
-LICENSE
+License
 =======
 
 Copyright 2010 Dirk Holtwick, holtwick.it

doc/pisa-en.html

@@ -139,6 +139,27 @@ <h2>Pages and Frames </h2>
 <pre>@page {
   margin: 1cm;
 } </pre>
+<p>Optionally, @page rules can have one pseudo-class (':left', or ':right') and/or one named page. See the example:</p>
+<pre>
+  @page template {
+    size: a4 portrait;
+    left: 5cm;
+    right: 2cm;
+  }
+
+  @page template:right {
+    size: a4 portrait;
+    left: 3cm;
+    right: 2cm;
+  }
+
+  @page template:left {
+    size: a4 portrait;
+    left: 2cm;
+    right: 3cm;
+  }
+
+</pre>
 <p>To define more frames just add some more <code>@frame</code> blocks. You may use the following properties to define the dimensions of the frame:</p>
 <ul>
   <li><code>marign</code></li>

requirements.xml

@@ -0,0 +1,7 @@
+PIL==1.1.7
+coverage==3.5
+html5lib==0.90
+httplib2==0.6.0
+nose==1.0.0
+pyPdf==1.13
+reportlab==2.5

test/cookbook.py

@@ -24,9 +24,8 @@
 Most people know how to write a page with HTML and CSS. Why not using these skills to dynamically generate PDF documents using it? The "pisa" project http://www.htmltopdf.org enables you to to this quite simple.
 """
 
-import cStringIO
-import ho.pisa as pisa
-import os
+from xhtml2pdf import pisa
+import cStringIO as StringIO
 
 # Shortcut for dumping all logs to the screen
 pisa.showLogging()
@@ -40,7 +39,7 @@ def HTML2PDF(data, filename, open=False):
     """
 
     pdf = pisa.CreatePDF(
-        cStringIO.StringIO(data),
+        StringIO.StringIO(data),
         file(filename, "wb"))
 
     if open and (not pdf.err):
@@ -72,4 +71,4 @@ def HTML2PDF(data, filename, open=False):
     </body></html>
     """
 
-    HTML2PDF(HTMLTEST, "test.pdf", open=True)
+    HTML2PDF(HTMLTEST, "test.pdf", open=False)