Better Docs.

README.rst

@@ -17,3 +17,7 @@ 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: https://docs.elephant.house/dpaste/
+
+.. image:: https://raw.githubusercontent.com/bartTC/dpaste/master/docs/_static/dpaste_de_screenshot.png
+    :alt: A screenshot of https://dpaste.de/
+    :width: 60%

docs/api.rst

@@ -1,45 +1,53 @@
-===
+============
-API
+API Endpoint
-===
+============
 
 dpaste provides a simple API endpoint to create new snippets. All you need to
-do is a simple ``POST`` request to the API endpoint ``/api/``::
+do is a simple ``POST`` request to the API endpoint, usually ``/api/``:
 
+.. http:post:: /api/
 
-    POST http://dpaste.de/api/
+   Create a new Snippet on this dpaste installation. It returns the full
+   URL that snippet was created.
 
+   **Example request**:
 
-Available POST data for an API call:
+   .. code-block:: bash
-====================================
 
-``content`` (required)
+      $ curl -X POST -F "format=url" -F "content=ABC" https:/dpaste.de/api/
-~~~~~~~~~~~~~~~~~~~~~~
 
-The UTF-8 encoded string you want to paste.
+      Host: dpaste.de
+      User-Agent: curl/7.54.0
+      Accept: */*
 
-``lexer`` (optional)
+   **Example response**:
-~~~~~~~~~~~~~~~~~~~~
 
-The lexer string key used for highlighting. See `lexer list`_  for a full list
+   .. sourcecode:: json
-of choices. Default: ``text``.
 
-``format`` (optional)
+      {
-~~~~~~~~~~~~~~~~~~~~~
+        "lexer": "python",
+        "url": "https://dpaste.de/EBKU",
+        "content": "ABC"
+      }
 
-The format of the API response. Choices are:
+   :form content: (required) The UTF-8 encoded string you want to paste.
 
-* ``default`` — Returns a full qualified URL wrapped in quotes. Example::
+   :form lexer: (optional) The lexer string key used for highlighting. See
+    the ``CODE_FORMATTER`` property in :ref:`settings` for a full list
+    of choices. Default: ``_code``.
 
-    "https://dpaste.de/xsWd"
+   :form format: (optional) The format of the API response. Choices are:
 
-* ``url`` — Returns the full qualified URL to the snippet, without surrounding
+    * ``default`` — Returns a full qualified URL wrapped in quotes.
-  quotes, but with a line break. Example::
+      Example: ``"https://dpaste.de/xsWd"``
 
-    https://dpaste.de/xsWd\n
+    * ``url`` — Returns the full qualified URL to the snippet, without surrounding
+      quotes, but with a line break. Example: ``https://dpaste.de/xsWd\n``
 
-* ``json`` — Returns a JSON object containing the URL, lexer and content of the
+    * ``json`` — Returns a JSON object containing the URL, lexer and content of the
-  the snippet. Example::
+      the snippet. Example:
 
+      .. code-block:: json
 
           {
             "url": "https://dpaste.de/xsWd",
@@ -48,26 +56,24 @@ The format of the API response. Choices are:
           }
 
 
-``expires`` (optional)
+   :form expires: (optional) A keyword to indicate the lifetime of a snippet in
-~~~~~~~~~~~~~~~~~~~~~~
+    seconds. The values are
+    predefined by the server. Calling this with an invalid value returns a HTTP 400
+    BadRequest together with a list of valid values. Default: ``2592000``. In the
+    default configuration valid values are:
 
-A keyword to indicate the lifetime of a snippetn in seconds. The values are
+    * onetime
-predefined by the server. Calling this with an invalid value returns a HTTP 400
+    * never
-BadRequest together with a list of valid values. Default: ``2592000``. In the
+    * 3600
-default configuration valid values are:
+    * 604800
+    * 2592000
 
-* onetime
+   :form filename: (optional) A filename which we use to determine a lexer, if
-* never
+    ``lexer`` is not set. In case we can't determine a file, the lexer will
-* 3600
+    fallback to ``plain`` code (no highlighting). A given ``lexer`` will overwrite
-* 604800
+    any filename! Example:
-* 2592000
 
-``filename`` (optional)
+    .. code-block:: json
-~~~~~~~~~~~~~~~~~~~~~~~
-
-A filename which we use to determine a lexer, if ``lexer`` is not set. In case
-we can't determine a file, the lexer will fallback to ``plain`` code (no
-highlighting). A given ``lexer`` will overwrite any filename! Example::
 
         {
           "url": "https://dpaste.de/xsWd",
@@ -76,7 +82,9 @@ highlighting). A given ``lexer`` will overwrite any filename! Example::
           "content": "The text body of the snippet."
         }
 
-This will create a ``python`` highlighted snippet. However in this example::
+    This will create a ``python`` highlighted snippet. However in this example:
+
+    .. code-block:: json
 
         {
           "url": "https://dpaste.de/xsWd",
@@ -85,44 +93,37 @@ This will create a ``python`` highlighted snippet. However in this example::
           "content": "The text body of the snippet."
         }
 
-Since the lexer is set too, we will create a ``php`` highlighted snippet.
+    Since the lexer is set too, we will create a ``php`` highlighted snippet.
 
-.. note:: Since ``lexer`` defaults to ``python`` you have to specifically
+   :statuscode 200: No Error.
-    unset it when using ``filename``.
+   :statuscode 400: One of the above form options was invalid,
+    the response will contain a meaningful error message.
 
-.. hint:: You need to adjust the setting ``DPASTE_BASE_URL`` which is used
+.. hint:: If yuo have a standalone installation and your API returns
-    to generate the full qualified URL in the API response. See :doc:`settings`.
+    ``https://dpaste.de/`` as the domain, you need to adjust the setting
+    ``BASE_URL`` property. See :ref:`settings`.
 
-.. note:: When creating new snippets via the API, they won't be listed on the
-    history page since they are related to a browser session.
 
-.. _lexer list: https://github.com/bartTC/dpaste/blob/master/dpaste/highlight.py#L25
+Third party API integration into editors
+========================================
 
-Example code snippets:
+subdpaste
-======================
+    a Sublime Editor plugin: https://github.com/bartTC/SubDpaste
+Marmalade
+    an Emacs plugin: http://marmalade-repo.org/packages/dpaste_de
+atom-dpaste
+    for the Atom editor: https://atom.io/packages/atom-dpaste
 
-A sample Python 2 script to publish snippets::
+You can also paste your file content to the API via curl, directly from the
+command line:
 
-    #!/usr/bin/env python
+.. code-block:: bash
-
-    import urllib
-    import urllib2
-    import sys
-
-    def paste_code():
-        request = urllib2.Request(
-            'https://dpaste.de/api/',
-            urllib.urlencode([('content', sys.stdin.read())]),
-        )
-        response = urllib2.urlopen(request)
-        # Strip surrounding quotes (NB: response has no trailing newline)
-        print response.read()[1:-1]
-
-    if __name__ == '__main__':
-        paste_code()
-
-You can simply use curl to publish a whole file::
 
     $ alias dpaste="curl -F 'format=url' -F 'content=<-' https://dpaste.de/api/"
     $ cat foo.txt | dpaste
     https://dpaste.de/ke2pB
+
+.. note:: If you wrote or know a third party dpaste plugin or extension,
+    please open an *Issue* on Github_ and it's added here.
+
+.. _Github: https://github.com/bartTC/dpaste

docs/conf.py

@@ -41,6 +41,7 @@ release = ''
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
+    'sphinxcontrib.httpdomain',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -81,6 +82,12 @@ try:
     import sphinx_rtd_theme
     html_theme = "sphinx_rtd_theme"
     html_theme_path = ["_themes", ]
+    html_theme_options = {
+        'logo_only': True,
+        'display_version': False,
+    }
+    html_logo = "_static/logo.svg"
+
 except ImportError:
     html_theme = 'alabaster'
 

docs/index.rst

@@ -1,26 +1,50 @@
+.. _index:
+
 ======
 dpaste
 ======
 
-dpaste is a Django based pastebin. It's intended to run separately but its also
+.. image:: https://img.shields.io/pypi/v/dpaste.svg
-possible to be installed into an existing Django project like a regular app.
+    :target: https://pypi.org/project/dpaste/
 
-.. note:: dpaste requires at a minimum Python 3.4 and Django 1.11.
+.. image:: https://travis-ci.org/bartTC/dpaste.svg?branch=master
+    :target: https://travis-ci.org/bartTC/dpaste
 
-Contents:
+.. image:: https://api.codacy.com/project/badge/Coverage/185cfbe9b4b447e59a40f816c4a5ebf4
+    :target: https://www.codacy.com/app/bartTC/dpaste
+
+.. image:: https://api.codacy.com/project/badge/Grade/185cfbe9b4b447e59a40f816c4a5ebf4
+    :target: https://www.codacy.com/app/bartTC/dpaste
+
+
+dpaste is a pastebin_ application written in Python using the Django
+framework. You can find a live installation on `dpaste.de`_.
+
+.. image:: _static/dpaste_de_screenshot.png
+    :alt: A screenshot of https://dpaste.de/
+    :width: 60%
+
+The project is intended to run standalone as any regular Django Project,
+but it's also possible to install it into an existing project as a typical
+Django application.
+
+The code is open source and available on Github:
+https://github.com/bartTC/dpaste. If you found bugs, have problems or ideas with
+the project or the website installation, please create an *Issue* there.
+
+dpaste requires at a minimum **Python 3.4** and **Django 1.11**.
+
+Documentation
+=============
 
 .. toctree::
    :maxdepth: 1
 
-   local_development
+   standalone_installation
-   integration
+   project_installation
+   management_commands
    settings
    api
 
-..
+.. _dpaste.de: https://dpaste.de/
-    Indices and tables
+.. _pastebin: https://en.wikipedia.org/wiki/Pastebin
-    ==================
-    * :ref:`genindex`
-    * :ref:`modindex`
-    * :ref:`search`
-

docs/integration.rst

@@ -1,46 +0,0 @@
-=========================================
-Integrate dpaste into an existing project
-=========================================
-
-Install the latest dpaste release in your environment. This will install all
-necessary dependencies of dpaste as well::
-
-    pip install dpaste
-
-Add ``dpaste.apps.dpasteAppConfig`` to your ``INSTALLED_APPS``::
-
-    INSTALLED_APPS = (
-        'django.contrib.sessions',
-        'django.contrib.staticfiles',
-        # ...
-        'dpaste.apps.dpasteAppConfig',
-    )
-
-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 migrate the database schema::
-
-    manage.py migrate dpaste
-
-
-Purge expired snippets
-======================
-
-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/local_development.rst

@@ -1,54 +0,0 @@
-.. _local_development:
-
-=================
-Local Development
-=================
-
-
-Installation for local development
-==================================
-
-Local development is done with `pipenv`_ to maintain packages.
-
-Installation::
-
-    $ cd dpaste/
-
-    $ npm install
-    $ 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
-
-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/management_commands.rst

@@ -0,0 +1,41 @@
+.. _management_commands:
+
+===================
+Management Commands
+===================
+
+.. _purge_expired_snippets:
+
+Purge expired snippets
+======================
+
+dpaste ships with a management command ``cleanup_snippets`` that removes
+expired snippets. To run it locally do:
+
+.. code-block:: bash
+
+    $ pipenv run ./managepy cleanup_snippets
+
+Options
+-------
+
+--dry-run   Does not actually delete the snippets.
+            This is useful for local testing.
+
+Setup a Crontab
+---------------
+
+It's important that you setup a crontab or similar to remove expired snippets
+as soon as they reach their expiration date. A crontab line might look like:
+
+.. code-block:: bash
+
+    */5 * * * * /srv/dpaste.de/pipenv run manage.py cleanup_snippets > /dev/null
+
+
+.. note:: If you use the *database* session backend, you may also need to setup
+    a crontab that removes the expired entries from the session database.
+
+    See the related `Django Documentation`_ for details.
+
+.. _Django Documentation: https://docs.djangoproject.com/en/2.0/ref/django-admin/#django-admin-clearsessions

docs/project_installation.rst

@@ -0,0 +1,43 @@
+.. _project_installation:
+
+====================
+Project Installation
+====================
+
+.. important:: This documentation describes the installation of dpaste
+    into an existing Django project. If you want to run the application
+    standalone, see :ref:`standalone_installation`.
+
+Install the latest dpaste release in your environment. This will install all
+necessary dependencies of dpaste as well:
+
+.. code-block:: bash
+
+    $ pip install dpaste
+
+Add ``dpaste.apps.dpasteAppConfig`` to your ``INSTALLED_APPS`` list:
+
+.. code-block:: python
+
+    INSTALLED_APPS = (
+        'django.contrib.sessions',
+        # ...
+        'dpaste.apps.dpasteAppConfig',
+    )
+
+Add ``dpaste`` and the (optiona) ``dpaste_api`` url patterns:
+
+.. code-block:: python
+
+    urlpatterns = patterns('',
+        # ...
+
+        url(r'my-pastebin/', include('dpaste.urls.dpaste')),
+        url(r'my-pastebin/api/', include('dpaste.urls.dpaste_api')),
+    )
+
+Finally, migrate the database schema:
+
+.. code-block:: bash
+
+    $ manage.py migrate dpaste

docs/settings.rst

@@ -1,3 +1,5 @@
+.. _settings:
+
 ==========================
 Settings and Configuration
 ==========================
@@ -8,11 +10,11 @@ behavior.
 
 
 To do so, you need to override dpaste's AppConfig. This is a feature
-`introduced in Django 1.9`_ and allows you to set settings more programmatically.
+`introduced in Django 1.9`_ and allows you to set settings more
-
+programmatically.
-Please see the source of ``dpaste.apps.dpasteAppConfig`` for a full list
-of settings and functions you can override.
 
+See :ref:`current_appconfig` for a full list of settings and functions you
+can override.
 
 Example for your custom AppConfig:
 ==================================
@@ -34,3 +36,13 @@ Example for your custom AppConfig:
     ]
 
 .. _introduced in Django 1.9: https://docs.djangoproject.com/en/1.9/ref/applications/
+
+.. _current_appconfig:
+
+Current AppConfig with default values
+=====================================
+
+This is the file content of ``dpaste/apps.py``:
+
+.. literalinclude:: ../dpaste/apps.py
+    :language: python

docs/standalone_installation.rst

@@ -0,0 +1,125 @@
+.. _standalone_installation:
+
+==============================================
+Standalone Installation (or local development)
+==============================================
+
+.. important:: This documentation describes the installation of dpaste
+    as a standalone project, primarily for local development. If you want
+    to integrate the application into your existing Django project, see
+    :ref:`project_installation`.
+
+The project uses `pipenv`_ to maintain and install dependencies. Install it
+once globally with pip:
+
+.. code:: bash
+
+    $ pip install pipenv
+
+Then checkout the Git project code from Github and install the Node and
+Python dependencies.
+
+.. code-block:: bash
+
+    $ cd dpaste/
+    $ pipenv install --dev      # Installs the project and Python dependencies
+    $ npm install               # Installs the node dependencies and compiles
+                                # the static files (JS/CSS).
+
+Copy the sample settings file and edit it, to meet your needs:
+
+.. code-block:: bash
+
+    $ cp dpaste/settings/local.py.example dpaste/settings/local.py
+
+Run the testsuite to make sure everything was built correctly:
+
+.. code-block:: bash
+
+    $ pipenv run ./runtests.py
+
+Finally, to run the project on your local machine:
+
+.. code-block:: bash
+
+    $ pipenv run ./manage.py migrate
+    $ pipenv run ./manage.py runserver
+
+If this is a public, standalone installation, make sure you purge
+the expired snippets regularly. See :ref:`purge_expired_snippets`.
+
+CSS and Javascript development
+==============================
+
+Both CSS and Javascript files need to be compiled and compressed. The resulting
+files are not commited with the project code.
+
+There are some helper scripts you can invoke with ``npm``
+
+``npm start``
+    Compile the static files and run the Django runserver.
+``npm run build``
+    Compile static files.
+``npm run build-js``
+    Compile only JS files.
+``npm run build-css``
+    Compile only CSS files.
+``npm run watch-css``
+    Same as ``build-css`` but it automatically watches for changes in the
+    CSS files and re-compiles it.
+``npm run docs``
+    Compile this documentation. The result will be in ``docs/_build/html``.
+``npm run watch-docs``
+    Same as ``docs`` but it automatically watches for changes in the
+    documentation files and re-compiles the docs.
+
+
+.. note:: See ``npm run --list`` for the full and most recent list of
+    helper scripts.
+
+Testing with Tox
+================
+
+dpaste is continuously tested online with Travis_. You can also run the test
+suite locally with tox_. Tox automatically tests the project against multiple
+Python and Django versions.
+
+Similar to ``pipenv`` it's useful to have tox installed globally:
+
+.. code-block:: bash
+
+    $ pip install tox
+
+Then simply call it from the project directory.
+
+.. code-block:: bash
+
+    $ cd dpaste/
+    $ tox
+
+.. code-block:: text
+    :caption: Example tox output:
+
+    $ tox
+
+    py35-django-111 create: /tmp/tox/dpaste/py35-django-111
+    SKIPPED:InterpreterNotFound: python3.5
+    py36-django-111 create: /tmp/tox/dpaste/py36-django-111
+    py36-django-111 installdeps: django>=1.11,<1.12
+    py36-django-111 inst: /tmp/tox/dpaste/dist/dpaste-3.0a1.zip
+
+    ...................
+    ----------------------------------------------------------------------
+    Ran 48 tests in 1.724s
+    OK
+
+
+    SKIPPED:  py35-django-111: InterpreterNotFound: python3.5
+    SKIPPED:  py35-django-20: InterpreterNotFound: python3.5
+    py36-django-111: commands succeeded
+    py36-django-20: commands succeeded
+    congratulations :)
+
+.. _Travis: https://travis-ci.org/bartTC/dpaste
+.. _tox: http://tox.readthedocs.org/en/latest/
+.. _pipenv: https://docs.pipenv.org/