Tidy up docs & add documentation about settings

docs/contributing.rst

@@ -13,12 +13,16 @@ If you or your organisation does not accept these license terms then we cannot a
 Translations
 ------------
 
+.. image:: http://www.transifex.net/projects/p/django-helpdesk/resource/core/chart/image_png
+
 Although django-helpdesk has originally been written for the English language, there are already multiple translations to Spanish, Polish, and German and more translations are welcomed.
 
 Translations are handled using the excellent Transifex service which is much easier for most users than manually editing .po files. It also allows collaborative translation. If you want to help translate django-helpdesk into languages other than English, we encourage you to make use of our Transifex project:
 
 http://www.transifex.net/projects/p/django-helpdesk/resource/core/
 
+Once you have translated content via Transifex, please raise an issue on the project Github page to let us know it's ready to import.
+
 Code changes
 ------------
 
@@ -30,6 +34,15 @@ Commit messages should also explain *what*, precisely, has been changed.
 
 If you have any questions, please contact the project co-ordinator, Ross Poulton, at [email protected].
 
+Tests
+-----
+
+Currently, test coverage is very low. We're working on increasing this, and to make life easier we are using `Travis CI`_ for continuous integration. This means that the test suite is run every time a code change is made, so we can try and make sure we avoid basic bugs and other regressions.
+
+Please include tests in the ``tests/`` folder when committing code changes.
+
+.. _Travis CI: http://travis-ci.org/
+
 Database schema changes
 -----------------------
 

docs/custom_fields.rst

@@ -1,10 +1,8 @@
 Custom Fields
 =============
 
-As of February 2011, django-helpdesk supports custom fields on the ``Ticket`` model. These fields are created by using the Django administration tool, and are shown on both the public and staff submission forms. 
+django-helpdesk supports custom fields on the ``Ticket`` model. These fields are created by using the Django administration tool, and are shown on both the public and staff submission forms. You can use most Django field types including text, integer, boolean, and list.
 
-You can use most Django field types including text, integer, boolean, and list.
+The demo at http://django-helpdesk-demo.herokuapp.com contains an example of each type of custom field, including a mix of mandatory and optional fields.
 
-The demo at http://demo.jutdahelpdesk.com contains an example of each type of custom field, including a mix of mandatory and optional fields.
-
-Note that this feature is still in beta - it needs quite a bit of testing and no doubt has bugs!
+Custom fields are relatively inefficient, and you cannot search by them. They can be useful for tracking extra information that your organisation needs but that isn't supported out of the box.

docs/index.rst

@@ -3,6 +3,23 @@ Welcome to django-helpdesk's documentation!
 
 django-helpdesk is a Django application to manage helpdesk tickets for your internal helpdesk. It was formerly known as Jutda Helpdesk.
 
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   license
+   install
+   configuration
+   settings
+   spam
+   custom_fields
+   api
+   contributing
+
+
 How Does It Look?
 -----------------
 
@@ -18,7 +35,7 @@ Key Features
 
 django-helpdesk has been designed for small businesses who need to recieve, manage and respond to requests for help from customers. In this context *'customers'* may be external users, or other people within your company.
 
-* Tickets can be opened vi a email
+* Tickets can be opened via email
 * Multiple queues / categories of tickets
 * Integrated FAQ / knowledgebase
 
@@ -52,35 +69,8 @@ django-helpdesk is released under the BSD license, however it packages 3rd party
 Dependencies
 ------------
 
-1. Python 2.4+
-2. Django (1.2 or newer)
+1. Python 2.5+
+2. Django (1.3 or newer)
 3. South for database migrations (highly recommended, but not required). Download from http://south.aeracode.org/
-4. An existing **working** Django project with database etc. If you cannot log into the Admin, you won't get this product working!
-
-Translation
------------
-
-.. image:: http://www.transifex.net/projects/p/django-helpdesk/resource/core/chart/image_png
-
-If you want to help translate django-helpdesk into languages other than English, we encourage you to make use of our Transifex project.
-
-http://www.transifex.net/projects/p/django-helpdesk/resource/core/
-
-Feel free to request access to contribute your translations.
-
-Contents:
----------
-
-.. toctree::
-   :maxdepth: 2
-   :glob:
-
-   license
-   install
-   configuration
-   settings
-   spam
-   custom_fields
-   api
-   contributing
+4. An existing **working** Django project with database etc. If you cannot log into the Admin, you won't get this product working! This means you **must** run `syncdb` **before** you add ``helpdesk`` to your ``INSTALLED_APPS``.
 

docs/install.rst

@@ -60,9 +60,9 @@ Adding To Your Django Project
 
      ./manage.py migrate helpdesk
 
-4. [If you're not using django.contrib.staticfiles] Inside your ``STATIC_ROOT`` folder, create a new folder called ``helpdesk`` and copy the contents of ``helpdesk/static`` into it. Alternatively, create a symlink::
+4. Include your static files in your public web path::
 
-      ln -s /path/to/helpdesk/static/helpdesk /path/to/static/helpdesk
+      python manage.py collectstatic
 
 5. Inside your ``MEDIA_ROOT`` folder, inside the ``helpdesk`` folder, is a folder called ``attachments``. Ensure your web server software can write to this folder - something like this should do the trick::
 

docs/settings.rst

@@ -9,7 +9,7 @@ First, django-helpdesk needs  ``django.core.context_processors.request`` activat
                 ('django.core.context_processors.request',)
          )
 
-The following settings can be changed in your ``settings.py`` file to help change the way django-helpdesk operates.
+The following settings can be changed in your ``settings.py`` file to help change the way django-helpdesk operates. There are quite a few settings available to toggle functionality within django-helpdesk.
 
 HELPDESK_DEFAULT_SETTINGS
 -------------------------
@@ -26,3 +26,200 @@ If you want to override the default settings for your users, create ``HELPDESK_D
             'email_on_ticket_apichange': True,
             'tickets_per_page': 25
             }
+
+
+Generic Options
+===============
+These changes are visible throughout django-helpdesk
+
+HELPDESK_REDIRECT_TO_LOGIN_BY_DEFAULT
+-------------------------------------
+When a user visits "/", should we redirect to the login page instead of the default homepage?
+**Default:** ``HELPDESK_REDIRECT_TO_LOGIN_BY_DEFAULT = False``
+
+HELPDESK_PREPEND_ORG_NAME
+-------------------------
+Customize helpdesk name on a few pages, i.e., your organization.
+**Default:** ``HELPDESK_PREPEND_ORG_NAME = False``
+
+HELPDESK_KB_ENABLED
+-------------------
+show knowledgebase links?
+**Default:** ``HELPDESK_KB_ENABLED = True``
+
+HELDPESK_KB_ENABLED_STAFF
+-------------------------
+Show knowledgebase links for staff users?
+**Default:** ``HELPDESK_KB_ENABLED_STAFF = False``
+
+HELPDESK_NAVIGATION_ENABLED
+---------------------------
+Show extended navigation by default, to all users, irrespective of staff status?
+**Default:** ``HELPDESK_NAVIGATION_ENABLED = False``
+
+HELPDESK_NAVIGATION_STATS_ENABLED
+---------------------------------
+Show 'stats' link in navigation bar for staff users?
+**Default:** ``HELPDESK_NAVIGATION_STATS_ENABLED = True``
+
+HELPDESK_SUPPORT_PERSON
+-----------------------
+Set this to an email address inside your organization and a footer below
+the 'Powered by django-helpdesk' will be shown, telling the user whom to contact
+in case they have technical problems.
+**Default:** ``HELPDESK_SUPPORT_PERSON = ""``
+
+HELPDESK_TRANSLATE_TICKET_COMMENTS
+----------------------------------
+Show dropdown list of languages that ticket comments can be translated into via Google Translate?
+**Default:** ``HELPDESK_TRANSLATE_TICKET_COMMENTS = False``
+
+HELPDESK_TRANSLATE_TICKET_COMMENTS_LANG
+---------------------------------------
+List of languages to offer. If set to false, all default google translate languages will be shown.
+**Default:** ``HELPDESK_TRANSLATE_TICKET_COMMENTS_LANG = ["en", "de", "fr", "it", "ru"]``
+
+HELPDESK_SHOW_CHANGE_PASSWORD
+-----------------------------
+Show link to 'change password' on 'User Settings' page?
+**Default:** ``HELPDESK_SHOW_CHANGE_PASSWORD = False``
+
+HELPDESK_FOLLOWUP_MOD
+---------------------
+Allow user to override default layout for 'followups' (work in progress)
+**Default:** ``HELPDESK_FOLLOWUP_MOD = False``
+
+HELPDESK_CUSTOM_WELCOME
+-----------------------
+Show custom welcome message in dashboard?
+**Default:** ``HELPDESK_CUSTOM_WELCOME = False``
+
+HELPDESK_AUTO_SUBSCRIBE_ON_TICKET_RESPONSE 
+------------------------------------------
+Auto-subscribe user to ticket as a 'CC' if (s)he responds to a ticket?
+**Default:** ``HELPDESK_AUTO_SUBSCRIBE_ON_TICKET_RESPONSE = False``
+
+
+Options shown on public pages
+=============================
+
+These options only change display of items on public-facing pages, not staff pages.
+
+HELPDESK_VIEW_A_TICKET_PUBLIC
+-----------------------------
+Show 'View a Ticket' section on public page?
+**Default:** ``HELPDESK_VIEW_A_TICKET_PUBLIC = True``
+
+HELPDESK_SUBMIT_A_TICKET_PUBLIC
+-------------------------------
+Show 'submit a ticket' section & form on public page?
+**Default:** ``HELPDESK_SUBMIT_A_TICKET_PUBLIC = True``
+
+HELPDESK_SHOW_KB_ON_HOMEPAGE
+----------------------------
+Should we should the KB categories on the homepage?
+**Default:** ``HELPDESK_SHOW_KB_ON_HOMEPAGE = False``
+
+
+Options that change ticket updates
+==================================
+
+HELPDESK_ALLOW_NON_STAFF_TICKET_UPDATE
+----------------------------
+Allow non-staff users to interact with tickets? This will also change how 'staff_member_required' 
+in staff.py will be defined.
+**Default:** ``HELPDESK_ALLOW_NON_STAFF_TICKET_UPDATE = False``
+
+HELPDESK_SHOW_EDIT_BUTTON_FOLLOW_UP
+-----------------------------------
+Show edit buttons in ticket follow ups?
+**Default:** ``HELPDESK_SHOW_EDIT_BUTTON_FOLLOW_UP = True``
+
+HELPDESK_SHOW_DELETE_BUTTON_SUPERUSER_FOLLOW_UP
+-----------------------------------------------
+Show delete buttons in ticket follow ups if user is 'superuser'?
+**Default:** ``HELPDESK_SHOW_DELETE_BUTTON_SUPERUSER_FOLLOW_UP = False``
+
+HELPDESK_SHOW_EDIT_BUTTON_TICKET_TOP
+------------------------------------
+Show ticket edit button on top of ticket description?
+**Default:** ``HELPDESK_SHOW_EDIT_BUTTON_TICKET_TOP = True``
+
+HELPDESK_SHOW_DELETE_BUTTON_TICKET_TOP
+--------------------------------------
+Show ticket delete button on top of ticket description?
+**Default:** ``HELPDESK_SHOW_DELETE_BUTTON_TICKET_TOP = True``
+
+HELPDESK_SHOW_HOLD_BUTTON_TICKET_TOP
+------------------------------------
+Show hold / unhold button on top of ticket description?
+**Default:** ``HELPDESK_SHOW_HOLD_BUTTON_TICKET_TOP = True``
+
+HELPDESK_UPDATE_PUBLIC_DEFAULT
+------------------------------
+Make all updates public by default? This will hide the 'is this update public' checkbox.
+**Default:** ``HELPDESK_UPDATE_PUBLIC_DEFAULT = True``
+
+HELPDESK_STAFF_ONLY_TICKET_OWNERS
+---------------------------------
+Only show staff users in ticket owner drop-downs?
+**Default:** ``HELPDESK_STAFF_ONLY_TICKET_OWNERS = False``
+
+HELPDESK_STAFF_ONLY_TICKET_CC
+-----------------------------
+Only show staff users in ticket cc drop-down?
+**Default:** ``HELPDESK_STAFF_ONLY_TICKET_CC = False``
+
+
+Staff Ticket Creation Settings
+==============================
+
+HELPDESK_CREATE_TICKET_HIDE_ASSIGNED_TO
+---------------------------------------
+Hide the 'assigned to' / 'Case owner' field from the 'create_ticket' view? It'll still show on the ticket detail/edit form.
+**Default:** ``HELPDESK_CREATE_TICKET_HIDE_ASSIGNED_TO = False``
+
+
+Dashboard Settings
+==================
+
+These will change the way the *dashboard* is displayed to staff users when they login.
+
+HELPDESK_DASHBOARD_SHOW_DELETE_UNASSIGNED
+-----------------------------------------
+Show delete button next to unassigned tickets?
+**Default:** ``HELPDESK_DASHBOARD_SHOW_DELETE_UNASSIGNED = True``
+
+HELPDESK_DASHBOARD_HIDE_EMPTY_QUEUES
+------------------------------------
+Hide empty queues in dashboard overview?
+**Default:** ``HELPDESK_DASHBOARD_HIDE_EMPTY_QUEUES = True``
+
+HELPDESK_DASHBOARD_BASIC_TICKET_STATS
+-------------------------------------
+Show basic ticket stats on dashboard? This may have performance implications for busy helpdesks.
+**Default:** ``HELPDESK_DASHBOARD_BASIC_TICKET_STATS = False``
+
+
+Footer Display Settings
+=======================
+
+HELPDESK_FOOTER_SHOW_API_LINK
+Show link to API documentation at bottom of page?
+**Default:** ``HELPDESK_FOOTER_SHOW_API_LINK = True``
+
+HELPDESK_FOOTER_SHOW_CHANGE_LANGUAGE_LINK
+-----------------------------------------
+Show the 'change language' link at bottom of page? Useful if you have a multilingual helpdesk.
+**Default:** ``HELPDESK_FOOTER_SHOW_CHANGE_LANGUAGE_LINK = False``
+
+Default E-Mail Settings
+=======================
+
+The following settings default to ``None`` but can be set as defaults, rather than setting them per-queue.
+
+``QUEUE_EMAIL_BOX_TYPE``
+``QUEUE_EMAIL_BOX_SSL``
+``QUEUE_EMAIL_BOX_HOST````
+``QUEUE_EMAIL_BOX_USER``
+``QUEUE_EMAIL_BOX_PASSWORD``