From 57bd42472381b0692b4a70641bcaab94e1d7bd16 Mon Sep 17 00:00:00 2001 From: Martin Mahner Date: Fri, 22 Jun 2018 12:37:54 +0200 Subject: [PATCH] Updated Documentation --- docs/conf.py | 2 +- docs/index.rst | 4 +- docs/installation.rst | 26 -------- docs/integration.rst | 4 +- docs/local_development.rst | 56 +++++++++++++++++ docs/settings.rst | 120 +++++++------------------------------ docs/testing.rst | 20 ------- 7 files changed, 81 insertions(+), 151 deletions(-) delete mode 100644 docs/installation.rst create mode 100644 docs/local_development.rst delete mode 100644 docs/testing.rst diff --git a/docs/conf.py b/docs/conf.py index 574829f..d1cfc8b 100644 --- a/docs/conf.py +++ b/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'] diff --git a/docs/index.rst b/docs/index.rst index a716ecd..e30e05d 100644 --- a/docs/index.rst +++ b/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 - installation + local_development integration settings api diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index c4d11de..0000000 --- a/docs/installation.rst +++ /dev/null @@ -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/ diff --git a/docs/integration.rst b/docs/integration.rst index 20e2978..785797c 100644 --- a/docs/integration.rst +++ b/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 ====================== diff --git a/docs/local_development.rst b/docs/local_development.rst new file mode 100644 index 0000000..c87cb06 --- /dev/null +++ b/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/ + + diff --git a/docs/settings.rst b/docs/settings.rst index 8af104c..c9ae60f 100644 --- a/docs/settings.rst +++ b/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`` - Integer. Length of the random slug for each new snippet. In the rare - case an existing slug is generated again, the length will increase by - one more character. - Default: ``4`` +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. - ``DPASTE_SLUG_CHOICES`` - String. A string of characters which are used to create the random slug. - Default: ``abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNOPQRSTUVWXYZ1234567890`` +Please see the source of ``dpaste.apps.dpasteAppConfig`` for a full list +of settings and functions you can override. - ``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`` +Example for your custom AppConfig: +================================== - ``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`` +.. code-block:: python - ``DPASTE_LEXER_CHOICES`` - Choices. A tuple of choices of Pygments lexers used in the lexer - dropdown. Here is the full `lexer list`_ which is currently used. - Example:: + # settings.py + from dpaste.apps import dpasteAppConfig - DPASTE_LEXER_CHOICES = ( - ('delphi', 'Delphi'), - ('php', 'PHP'), - ('text', 'Text'), - ) + class MyBetterDpasteAppConfig(dpasteAppConfig): + SLUG_LENGTH = 8 + LEXER_DEFAULT = 'js' - ``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 _ - DPASTE_EXPIRE_CHOICES = ( - (3600, _('In one hour')), - (3600 * 24 * 7, _('In one week')), - (3600 * 24 * 30, _('In one month')), - (3600 * 24 * 30 * 12 * 100, _('100 Years')), - ) + INSTALLED_APPS = [ + 'myproject.settings.MyBetterDpasteAppConfig', + ] - **One-Time snippets** are supported. One-Time snippets are automatically - 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 +.. _introduced in Django 1.9: https://docs.djangoproject.com/en/1.9/ref/applications/ diff --git a/docs/testing.rst b/docs/testing.rst deleted file mode 100644 index 8f4cb29..0000000 --- a/docs/testing.rst +++ /dev/null @@ -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/