diff options
| -rw-r--r-- | docs/conf.py | 14 | ||||
| -rw-r--r-- | docs/index.rst | 49 | ||||
| -rw-r--r-- | docs/installation.rst | 57 | ||||
| -rw-r--r-- | docs/usage.rst | 2 |
4 files changed, 80 insertions, 42 deletions
diff --git a/docs/conf.py b/docs/conf.py index b224335..a8227a3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,6 +13,8 @@ import sys, os +from wkhtmltopdf import get_version + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -41,16 +43,16 @@ master_doc = 'index' # General information about the project. project = u'django-wkhtmltopdf' -copyright = u'2011, Charles Denton, George Hickman' +copyright = u'2012, Incuna Ltd' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.1' +version = get_version() # The full version, including alpha/beta/rc tags. -release = '0.1.2' +release = get_version() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -184,7 +186,7 @@ latex_elements = { # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'django-wkhtmltopdf.tex', u'django-wkhtmltopdf Documentation', - u'Charles Denton, George Hickman', 'manual'), + u'Incuna Ltd', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -214,7 +216,7 @@ latex_documents = [ # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'django-wkhtmltopdf', u'django-wkhtmltopdf Documentation', - [u'Charles Denton, George Hickman'], 1) + [u'Incuna Ltd'], 1) ] # If true, show URL addresses after external links. @@ -228,7 +230,7 @@ man_pages = [ # dir menu entry, description, category) texinfo_documents = [ ('index', 'django-wkhtmltopdf', u'django-wkhtmltopdf Documentation', - u'Charles Denton, George Hickman', 'django-wkhtmltopdf', 'One line description of project.', + u'Incuna Ltd', 'django-wkhtmltopdf', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/index.rst b/docs/index.rst index 04dec19..560d8af 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,53 @@ -===================================== +================== django-wkhtmltopdf -===================================== +================== -Render PDFs in Django using the `wkhtmltopdf`_ library. +``django-wkhtmltopdf`` allows a Django site to output dynamic PDFs. It utilises +the wkhtmltopdf_ library, allowing you to write using the technologies you know +- HTML and CSS - and output a PDF file. .. _wkhtmltopdf: http://code.google.com/p/wkhtmltopdf/ +Quickstart +========== + +.. code-block:: bash + + pip install django-wkhtmltopdf + +Grab the wkhtmltopdf binary_ for your platform. + +.. _binary: http://code.google.com/p/wkhtmltopdf/downloads/list + +``settings.py`` + +.. code-block:: python + + INSTALLED_APPS = ( + # ... + 'wkhtmltopdf', + # ... + ) + +``urls.py`` + +.. code-block:: python + + from django.conf.urls.defaults import url, patterns + from wkhtmltopdf.views import PDFTemplateView + + urlpatterns = patterns('', + url(r'^pdf/$', PDFTemplateView.as_view(template_name='my_template.html', + filename='my_pdf.pdf'), name='pdf'), + ) + +Contribute +========== + +You can fork the project on Github_. + +.. _Github: http://github.com/incuna/django-wkhtmltopdf + Contents ======== @@ -14,4 +56,3 @@ Contents installation usage - diff --git a/docs/installation.rst b/docs/installation.rst index 98aadc0..0cf448b 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,18 +1,19 @@ -Installation -============ +Full Installation Notes +======================= -Package -------- -PyPI -~~~~ +Installing the Package +---------------------- + +From PyPI +~~~~~~~~~ .. code-block:: bash pip install django-wkhtmltopdf -GitHub -~~~~~~ +From source +~~~~~~~~~~~ .. code-block:: bash @@ -21,38 +22,34 @@ GitHub python setup.py install -Binary ------- - -Find the relevant download link on the ``wkhtmltopdf`` project `downloads page`_. - -This requires libfontconfig (on Ubuntu: ``sudo aptitude install libfontconfig``). - -.. _downloads page: http://code.google.com/p/wkhtmltopdf/downloads/list +Installing the Binary +--------------------- -.. note:: +Find the relevant version of the ``wkhtmltopdf`` binary from the project +`downloads page`_. - The wkhtmltopdf downloads page can be quite confusing. Make sure you get - wkhtmltopdf (there are a few different libraries on there) and the correct platform. +You might need to install ``libfontconfig``. +You can alternatively install wkhtmltopdf from source via Homebrew or +apt-get/aptitude, but as this requires a full compilation of QT it's not +recommended. .. note:: - At the time of writing it was possible to install wkhtmltopdf from Homebrew - and apt-get/aptitude but required compilation of QT which can take quite a - while so the binary installation is recommended. - + The downloads page can be quite confusing. Make sure you get wkhtmltopdf + (there are a few different libraries on there) and the correct platform. .. note:: - There is an known issue on 64bit machines where wkhtmltopdf will fail + There is an known issue on 64bit machines where ``wkhtmltopdf`` will fail silently. `This page`_ details ways to get around this but the easiest way to fix the issue is to install the 32bit binary. +.. _downloads page: http://code.google.com/p/wkhtmltopdf/downloads/list .. _this page: http://code.google.com/p/wkhtmltopdf/wiki/static -Django ------- +Setting up your Django +---------------------- Add ``wkhtmltopdf`` to your ``INSTALLED_APPS``: @@ -64,13 +61,11 @@ Add ``wkhtmltopdf`` to your ``INSTALLED_APPS``: # ... ) -By default it will execute the first wkhtmltopdf command found on your ``PATH``. +By default it will try to execute the ``wkhtmltopdf`` command from your ``PATH``. -If you can't add wkhtmltopdf to your ``PATH``, you can set ``WKHTMLTOPDF_CMD`` to a specific execuatable: - -e.g.: in ``settings.py`` +If you can't add wkhtmltopdf to your ``PATH`` or you want to use some other +version, you can use the ``WKHTMLTOPDF_CMD`` setting: .. code-block:: python WKHTMLTOPDF_CMD = '/path/to/my/wkhtmltopdf' - diff --git a/docs/usage.rst b/docs/usage.rst index fe883f3..8f8d797 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -29,7 +29,7 @@ Point a URL at PDFTemplateView: .. code-block:: python from django.conf.urls.defaults import * - from django_wkhtmltopdf.views import PDFTemplateView + from wkhtmltopdf.views import PDFTemplateView urlpatterns = patterns('', |