From 85daece4ed63036ef9906d795c5e1cbe38253800 Mon Sep 17 00:00:00 2001
From: Simon Law <simon.law@ecometrica.com>
Date: Wed, 25 Jul 2012 15:40:01 -0400
Subject: Documentation updates for new and updated behaviour.

---
 docs/index.rst    |  1 +
 docs/settings.rst | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/usage.rst    | 61 ++++++++++++++++++++++++++++++++++++------------
 3 files changed, 116 insertions(+), 15 deletions(-)
 create mode 100644 docs/settings.rst

(limited to 'docs')

diff --git a/docs/index.rst b/docs/index.rst
index 560d8af..817db3f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -56,3 +56,4 @@ Contents
 
     installation
     usage
+    settings
diff --git a/docs/settings.rst b/docs/settings.rst
new file mode 100644
index 0000000..7b5116a
--- /dev/null
+++ b/docs/settings.rst
@@ -0,0 +1,69 @@
+Settings
+========
+
+Available settings
+------------------
+
+Here's a full list of available settings,
+in alphabetical order,
+and their default values.
+
+WKHTMLTOPDF_CMD
+~~~~~~~~~~~~~~~
+
+Default: ``'wkhtmltopdf'``
+
+The name of the ``wkhtmltopdf`` binary.
+
+If there are no path components,
+this app will look for the binary using the default OS paths.
+
+WKHTMLTOPDF_CMD_OPTIONS
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Default: ``{'quiet': True}``
+
+A dictionary of command-line arguments to pass to the ``wkhtmltopdf``
+binary.
+Keys are the name of the flag and values are arguments for the flag.
+
+To pass a simple flag,
+for example:
+``wkhtmltopdf --disable-javascript``:
+
+.. code-block:: python
+
+    WKHTMLTOPDF_CMD_OPTIONS = {'disable-javascript': True}
+
+To pass a flag with an argument,
+for example:
+``wkhtmltopdf --title 'TPS Report'``:
+
+.. code-block:: python
+
+    WKHTMLTOPDF_CMD_OPTIONS = {'title': 'TPS Report'}
+
+
+WKHTMLTOPDF_DEBUG
+~~~~~~~~~~~~~~~~~
+
+Default: same as :py:data:`settings.DEBUG`
+
+A boolean that turns on/off debug mode.
+
+WKHTMLTOPDF_ENV
+~~~~~~~~~~~~~~~
+
+Default: ``None``
+
+An optional dictionary of environment variables to override,
+when running the ``wkhtmltopdf`` binary.
+Keys are the name of the environment variable.
+
+A common use of this is to set the ``DISPLAY`` environment variable
+to another X server,
+when using ``wkhtmltopdf --use-xserver``:
+
+.. code-block:: python
+
+    WKHTMLTOPDF_ENV = {'DISPLAY': ':2'}
diff --git a/docs/usage.rst b/docs/usage.rst
index 8f8d797..7d031d1 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -1,19 +1,48 @@
 Usage
 =====
 
-The ``PDFTemplateView`` takes a selection of variables, most of which get passed
-to the underlying wkhtmltopdf binary. The exceptions are:
+The :py:class:`PDFTemplateView` is a Django class-based view.
+By default, it uses :py:class:`PDFTemplateResponse` to render an HTML
+template to PDF.
+It accepts the following class attributes:
 
-* filename
-* footer_template
-* header_template
-* response
-* template_name
+:py:attr:`template_name`
+    The full name of a template to use as the body of the PDF.
 
-wkhtmltopdf options can be found by running ``wkhtmltopdf --help``. Unfortunately
-they don't provide hosted documentation. Any variables you pass to django-wkhtmltopdf
-need to be underscored. They will be converted to hyphenated variables for use with
-the wkhtmltopdf binary.
+:py:attr:`header_template`
+    Optional.
+    The full name of a template to use as the header on each page.
+
+:py:attr:`footer_template`
+    Optional.
+    The full name of a template to use as the footer on each page.
+
+:py:attr:`filename`
+    The filename to use when responding with an attachment containing
+    the PDF.
+    Default is ``'rendered_pdf.pdf'``.
+
+    If ``None``, the view returns the PDF output inline,
+    not as an attachment.
+
+:py:attr:`response_class`
+    The response class to be returned by :py:meth:`render_to_response`
+    method.
+    Default is :py:class:`PDFTemplateResponse`.
+
+:py:attr:`html_response_class`
+    The response class to be returned by :py:meth:`render_to_response`
+    method, when rendering as HTML.
+    See note below.
+    Default is :py:class:`TemplateResponse`.
+
+:py:attr:`cmd_options`
+    The dictionary of command-line arguments passed to the underlying
+    ``wkhtmltopdf`` binary.
+    Default is ``{}``.
+
+    wkhtmltopdf options can be found by running ``wkhtmltopdf --help``.
+    Unfortunately they don't provide hosted documentation.
 
 .. note::
 
@@ -24,7 +53,7 @@ the wkhtmltopdf binary.
 Simple Example
 --------------
 
-Point a URL at PDFTemplateView:
+Point a URL at :py:class:`PDFTemplateView`:
 
 .. code-block:: python
 
@@ -43,7 +72,8 @@ Point a URL at PDFTemplateView:
 Advanced Example
 ----------------
 
-Point a URL (as above) at your own view that subclasses ``PDFTemplateView`` and
+Point a URL (as above) at your own view that subclasses
+:py:class:`PDFTemplateView`
 and override the sections you need to.
 
 .. code-block:: python
@@ -53,6 +83,7 @@ and override the sections you need to.
 
     class MyPDF(PDFTemplateView):
         filename = 'my_pdf.pdf'
-        margin_top = 3
         template_name = 'my_template.html'
-
+        cmd_options = {
+            'margin-top': 3,
+        }
-- 
cgit v1.2.3