Updated Documentation

docs/conf.py

@@ -27,7 +27,7 @@ import os
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinxcontrib.httpdomain']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -5,14 +5,14 @@ dpaste
 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.
 
+.. note:: dpaste requires at a minimum Python 3.4 and Django 1.11.
 
 Contents:
 
 .. toctree::
    :maxdepth: 1
 
-   testing
+   local_development
-   installation
    integration
    settings
    api

docs/installation.rst

@@ -1,26 +0,0 @@
-==================================
-Installation for local development
-==================================
-
-Local development is done with `pipenv`_ to maintain packages. 
-
-Installation::
-
-    $ cd dpaste/
-    $ pipenv install --three --dev
-
-Copy the settings file and edit it, to meet your needs::
-
-    $ cp dpaste/settings/local.py.example dpaste/settings/local.py
-    $ nano dpaste/settings/local.py
-
-Run the testsuite::
-
-    $ pipenv run ./runtests.py
-
-To run the project on your local machine::
-
-    $ pipenv run ./manage.py migrate
-    $ pipenv run ./manage.py runserver
-
-.. _pipenv: https://docs.pipenv.org/

docs/integration.rst

@@ -2,9 +2,6 @@
 Integrate dpaste into an existing project
 =========================================
 
-Dpaste needs at least Django 1.11+ 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::
 
@@ -32,6 +29,7 @@ Finally just migrate the database schema::
 
     manage.py migrate dpaste
 
+
 Purge expired snippets
 ======================
 

docs/local_development.rst

@@ -0,0 +1,56 @@
+.. _local_development:
+
+=================
+Local Development
+=================
+
+
+Installation for local development
+==================================
+
+Local development is done with `pipenv`_ to maintain packages.
+
+Installation::
+
+    $ cd dpaste/
+    $ pipenv install --dev
+
+Copy the settings file and edit it, to meet your needs::
+
+    $ cp dpaste/settings/local.py.example dpaste/settings/local.py
+    $ nano dpaste/settings/local.py
+
+Run the testsuite::
+
+    $ pipenv run ./runtests.py
+
+To run the project on your local machine::
+
+    $ pipenv run ./manage.py migrate
+    $ pipenv run ./manage.py runserver
+
+
+Testing
+=======
+
+dpaste is continuously tested on Travis_. You can also run the test
+suite locally with tox_::
+
+    $ cd dpaste/
+    $ pip install tox
+    $ tox --skip-missing-interpreters
+
+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/
+    $ pipenv install --dev
+    $ pipenv run ./runtests.py
+
+.. _Travis: https://travis-ci.org/bartTC/dpaste
+.. _tox: http://tox.readthedocs.org/en/latest/
+
+
+.. _pipenv: https://docs.pipenv.org/
+
+

docs/settings.rst

@@ -1,114 +1,36 @@
-====================
+==========================
-Settings to override
+Settings and Configuration
-====================
+==========================
 
 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:
+behavior.
 
-.. glossary::
 
-    ``DPASTE_SLUG_LENGTH``
+To do so, you need to override dpaste's AppConfig. This is a feature
-        Integer. Length of the random slug for each new snippet. In the rare
+`introduced in Django 1.9`_ and allows you to set settings more programmatically.
-        case an existing slug is generated again, the length will increase by
-        one more character.
-        Default: ``4``
 
-    ``DPASTE_SLUG_CHOICES``
+Please see the source of ``dpaste.apps.dpasteAppConfig`` for a full list
-        String. A string of characters which are used to create the random slug.
+of settings and functions you can override.
-        Default: ``abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNOPQRSTUVWXYZ1234567890``
 
-    ``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``
+Example for your custom AppConfig:
-        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``
+.. code-block:: python
-        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_CHOICES``
+    # settings.py
-        Choices. A tuple of choices of Pygments lexers used in the lexer
+    from dpaste.apps import dpasteAppConfig
-        dropdown. Here is the full `lexer list`_ which is currently used.
-        Example::
 
-            DPASTE_LEXER_CHOICES = (
+    class MyBetterDpasteAppConfig(dpasteAppConfig):
-                ('delphi', 'Delphi'),
+        SLUG_LENGTH = 8
-                ('php', 'PHP'),
+        LEXER_DEFAULT = 'js'
-                ('text', 'Text'),
-            )
 
-    ``DPASTE_EXPIRE_CHOICES``
+    # ...
-        Choices. A tuple of seconds and a descriptive string used in the lexer
-        expiration dropdown. Example::
 
-            from django.utils.translation import ugettext_lazy as _
+    INSTALLED_APPS = [
-            DPASTE_EXPIRE_CHOICES = (
+        'myproject.settings.MyBetterDpasteAppConfig',
-                (3600, _('In one hour')),
+    ]
-                (3600 * 24 * 7, _('In one week')),
-                (3600 * 24 * 30, _('In one month')),
-                (3600 * 24 * 30 * 12 * 100, _('100 Years')),
-            )
 
-        **One-Time snippets** are supported. One-Time snippets are automatically
+.. _introduced in Django 1.9: https://docs.djangoproject.com/en/1.9/ref/applications/
-        deleted once a defined view count has reached (Default: ``2``). To
-        enable one-time snippets you have to add a choice ``onetime`` to the
-        expire choices::
-
-            from django.utils.translation import ugettext_lazy as _
-            DPASTE_EXPIRE_CHOICES = (
-                ('onetime', _('One-Time snippet')),
-                (3600, _('In one hour')),
-                (3600 * 24 * 7, _('In one week')),
-                (3600 * 24 * 30, _('In one month')),
-            )
-
-        You can also set the maximum view count after what the snippet gets
-        deleted. The default is ``2``. One view is from the author, one view
-        is from another user::
-
-            DPASTE_ONETIME_LIMIT = 2
-
-        **Infinite snippets** are supported. You can keep snippets forever when
-        you set the choice key to ``never``. The management command will ignore
-        these snippets::
-
-            from django.utils.translation import ugettext_lazy as _
-            DPASTE_EXPIRE_CHOICES = (
-                (3600, _('In one hour')),
-                ('never', _('Never')),
-            )
-
-    ``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]``.
-
-    ``DPASTE_ENABLE_GIST``
-        **Removed in Version 2.13!**
-        Boolean. Whether to display the Gist button for re-pasting to GitHub.
-        Default: ``True``
-
-        ..warning: This feature was removed in v2.11.
-
-    ``DPASTE_DEFAULT_GIST_NAME``
-        **Removed in Version 2.13!**
-        String. The filename used when pasting a snippet on Github Gist.
-        Default: ``dpaste.de_snippet.py``
-
-    ``DPASTE_DEFAULT_GIST_DESCRIPTION``
-        **Removed in Version 2.13!**
-        String. The filename used when pasting a snippet on Github Gist.
-        Default: ``dpaste.de_snippet.py``
-
-    ``DPASTE_JQUERY_URL``
-        String. URL to use for jQuery.
-        Default: ``//ajax.googleapis.com/ajax/libs/jquery/1/jquery.js``
-
-.. _lexer list: https://github.com/bartTC/dpaste/blob/master/dpaste/highlight.py#L25

docs/testing.rst

@@ -1,20 +0,0 @@
-=============================
-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 --skip-missing-interpreters
-
-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/
-    $ pipenv install --three --dev
-    $ pipenv run python runtests.py
-
-.. _Travis: https://travis-ci.org/bartTC/dpaste
-.. _tox: http://tox.readthedocs.org/en/latest/