Added docs.

.gitignore

@@ -1,3 +1,4 @@
 *.pyc
 dpaste/settings/local.py
 dpaste.egg-info
+docs/_build

README.rst

@@ -2,79 +2,9 @@
 dpaste
 ======
 
-.. image:: https://travis-ci.org/bartTC/dpaste.png?branch=master
-    :target: https://travis-ci.org/bartTC/dpaste
-.. image:: https://coveralls.io/repos/bartTC/dpaste/badge.png?branch=master
-    :target: https://coveralls.io/r/bartTC/dpaste?branch=master
-
 dpaste is a Django based pastebin. It's intended to run separately but its also
 possible to be installed into an existing Django project like a regular app.
 
 You can find a live example on http://dpaste.de/
 
------------------------------
+Further documentation can be found here:
-Testing and local development
------------------------------
-
-dpaste is continuously tested on Travis_. You can also run the test
-suite locally with tox_::
-
-    $ cd dpaste/
-    $ pip install tox
-    $ tox
-
-A more manual approach is installing it all by hand in a virtual environment.
-This is also the preferred way to setup an environment for local development::
-
-    $ cd dpaste/
-    $ pip install -e .
-    $ pip install -r requirements.txt
-    $ python runtests.py
-
-.. _Travis: https://travis-ci.org/bartTC/dpaste
-.. _tox: http://tox.readthedocs.org/en/latest/
-
------------------------------------------
-Integrate dpaste into an existing project
------------------------------------------
-
-Dpaste needs at least Django 1.4+ and is tested on Python 2.7 as well as
-Python 3.3.
-
-Install the latest dpaste release in your environment. This will install all
-necessary dependencies of dpaste as well::
-
-    pip install dpaste
-
-Add ``dpaste`` and (preferred) ``south`` to your ``INSTALLED_APPS``::
-
-    INSTALLED_APPS = (
-        'django.contrib.sessions',
-        'django.contrib.staticfiles',
-        # ...
-
-        'mptt',
-        'dpaste',
-        # 'south', (supported)
-    )
-
-Add ``dpaste`` and if you want the ``dpaste_api`` to your urlpatterns::
-
-    urlpatterns = patterns('',
-        # ...
-
-        url(r'pastebin/', include('dpaste.urls.dpaste')),
-        url(r'pastebin/api/', include('dpaste.urls.dpaste_api')),
-    )
-
-Finally just ``syncdb`` or if you use South, migrate::
-
-    manage.py migrate dpaste
-
-Do not forget to setup a cron job to purge expired snippets. You need to
-run the management command ``cleanup_snippets``. A cron job I use looks like::
-
-    30 * * * * /srv/dpaste.de/bin/python /srv/dpaste.de/bin/manage.py cleanup_snippets > /dev/null
-
-Note also that dpaste does *not* come with Django admin integration. You need
-to setup an register the models in an ``admin.py`` yourself.

docs/conf.py

@@ -96,9 +96,14 @@ pygments_style = 'sphinx'
 
 # -- Options for HTML output ----------------------------------------------
 
+import sphinx_rtd_theme
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+# html_theme = 'default'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/index.rst

@@ -1,21 +1,23 @@
-.. dpaste documentation master file, created by
+======
-   sphinx-quickstart on Wed Dec 18 10:56:20 2013.
+dpaste
-   You can adapt this file completely to your liking, but it should at least
+======
-   contain the root `toctree` directive.
+
+dpaste is a Django based pastebin. It's intended to run separately but its also
+possible to be installed into an existing Django project like a regular app.
 
-Welcome to dpaste's documentation!
-==================================
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
+   testing
+   integration
+   settings
 
-
+..
     Indices and tables
     ==================
-
     * :ref:`genindex`
     * :ref:`modindex`
     * :ref:`search`

docs/integration.rst

@@ -0,0 +1,48 @@
+=========================================
+Integrate dpaste into an existing project
+=========================================
+
+Dpaste needs at least Django 1.4+ and is tested on Python 2.7 as well as
+Python 3.3.
+
+Install the latest dpaste release in your environment. This will install all
+necessary dependencies of dpaste as well::
+
+    pip install dpaste
+
+Add ``dpaste`` and (preferred) ``south`` to your ``INSTALLED_APPS``::
+
+    INSTALLED_APPS = (
+        'django.contrib.sessions',
+        'django.contrib.staticfiles',
+        # ...
+
+        'mptt',
+        'dpaste',
+        # 'south', (supported)
+    )
+
+Add ``dpaste`` and if you want the ``dpaste_api`` to your urlpatterns::
+
+    urlpatterns = patterns('',
+        # ...
+
+        url(r'pastebin/', include('dpaste.urls.dpaste')),
+        url(r'pastebin/api/', include('dpaste.urls.dpaste_api')),
+    )
+
+Finally just ``syncdb`` or if you use South, migrate::
+
+    manage.py migrate dpaste
+
+Do not forget to setup a cron job to purge expired snippets. You need to
+run the management command ``cleanup_snippets``. A cron job I use looks like::
+
+    30 * * * * /srv/dpaste.de/bin/python /srv/dpaste.de/bin/manage.py cleanup_snippets > /dev/null
+
+Note also that dpaste does *not* come with Django admin integration. You need
+to setup an register the models in an ``admin.py`` yourself.
+
+.. note::
+
+    For further customization see :doc:`settings`.

docs/settings.rst

@@ -0,0 +1,64 @@
+====================
+Settings to override
+====================
+
+When dpaste is installed as a standalone service or integrated into an existing
+project there are various settings you can override to adjust dpaste's
+behavior without touching the code:
+
+.. glossary::
+
+    ``DPASTE_SLUG_LENGTH``
+        Integer. Length of the random slug for each new snippet.
+        Default: ``4``
+
+    ``DPASTE_SLUG_CHOICES``
+        String. A string of characters which are used to create the random slug.
+        Default: ``abcdefghijkmnopqrstuvwwxyzABCDEFGHIJKLOMNOPQRSTUVWXYZ1234567890``
+
+    ``DPASTE_LEXER_DEFAULT``
+        String. The lexer key that is pre-selected in the dropdown. Note that
+        this is only used if the user has not saved a snippet before, otherwise
+        we use the last-used lexer. Default: ``python``
+
+    ``DPASTE_MAX_CONTENT_LENGTH``
+        Integer. Maximum number of bytes per snippet. Default: ``250 * 1024 * 1024``
+
+    ``DPASTE_MAX_SNIPPETS_PER_USER``
+        Integer. Maximum number of snippets we save in teh user session and
+        display on the history page. Default: ``10``
+
+    ``DPASTE_BASE_URL``
+        String. The full qualified hostname and path to the dpaste instance.
+        This is used to generate a link in the API response. Default: ``https://dpaste.de``
+
+    ``DPASTE_LEXER_LIST``
+        Choices. A tuple of choices of Pygments lexers used in the lexer
+        dropdown. Here is the full `lexer list`_ which is currently used.
+        Example::
+
+            DPASTE_LEXER_LIST = (
+                ('delphi', 'Delphi'),
+                ('php', 'PHP'),
+                ('text', 'Text'),
+            )
+
+    ``DPASTE_EXPIRE_CHOICES``
+        Choices. A tuple of seconds and a descriptive string used in the lexer
+        expiration dropdown. Example::
+
+            ugettext = lambda s: s
+            DPASTE_EXPIRE_CHOICES = (
+                (3600, ugettext(u'In one hour')),
+                (3600 * 24 * 7, ugettext(u'In one week')),
+                (3600 * 24 * 30, ugettext(u'In one month')),
+                (3600 * 24 * 30 * 12 * 100, ugettext(u'100 Years')),
+            )
+
+    ``DPASTE_EXPIRE_DEFAULT``
+        The key of the default value of ``DPASTE_EXPIRE_CHOICES``. Default:
+        ``3600 * 24 * 30 * 12 * 100`` or simpler: ``DPASTE_EXPIRE_CHOICES[2][0]``.
+
+
+
+.. _lexer list: https://github.com/bartTC/dpaste/blob/master/dpaste/highlight.py#L25

docs/testing.rst

@@ -0,0 +1,21 @@
+=============================
+Testing and local development
+=============================
+
+dpaste is continuously tested on Travis_. You can also run the test
+suite locally with tox_::
+
+    $ cd dpaste/
+    $ pip install tox
+    $ tox
+
+A more manual approach is installing it all by hand in a virtual environment.
+This is also the preferred way to setup an environment for local development::
+
+    $ cd dpaste/
+    $ pip install -e .
+    $ pip install -r requirements.txt
+    $ python runtests.py
+
+.. _Travis: https://travis-ci.org/bartTC/dpaste
+.. _tox: http://tox.readthedocs.org/en/latest/

requirements.txt

@@ -10,6 +10,7 @@ coverage==3.7
 tox==1.6.1
 docutils==0.11
 sphinx==1.2
+sphinx_rtd_theme
 
 # Deployment specific
 django-redis==3.3