Merge pull request #1165 from django-helpdesk/fix/make-demo-and-docs

Fix `make rundemo` and Documentation files

.gitignore

@@ -13,6 +13,7 @@ docs/doctrees/*
 *.swp
 .idea
 .tox/**
+.venv
 
 # ignore demo attachments that user might have added
 helpdesk/attachments/
@@ -25,4 +26,3 @@ demo/demodesk/media/helpdesk/attachments/DH-3/3/*
 demo/demodesk/media/helpdesk/attachments/DH-3/4/*
 !demo/demodesk/media/helpdesk/attachments/DH-3/3/someinfo.txt
 !demo/demodesk/media/helpdesk/attachments/DH-3/4/helpdesk.png
-

README.rst

@@ -28,11 +28,11 @@ get started with testing or developing `django-helpdesk`. The demo project
 resides in the `demo/` top-level folder.
 
 It's likely that you can start up a demo project server by running
-only the command:
+only the command (consider creating a virtualenv before):
 
     make rundemo
 
-or with docker:
+or with docker::
 
     docker build . -t demodesk
     docker run --rm -v "$PWD:/app" -p 8080:8080 demodesk
@@ -74,27 +74,33 @@ Developer Environment
 
 Follow these steps to set up your development environment to contribute to helpdesk:
  - check out the helpdesk app to your local file system::
-        git clone https://github.com/django-helpdesk/django-helpdesk.git
 
- - install a virtual environment
+    git clone https://github.com/django-helpdesk/django-helpdesk.git
-     - using virtualenv from the helpdesk base folder do::
+ 
-          virtualenv .venv && source .venv/bin/activate
+ - install a virtual environment and activate it::
+  
+    python -m venv .venv && source .venv/bin/activate
 
  - install the requirements for development::
+
     pip install -r requirements.txt -r requirements-dev.txt
 
- - install the requirements for testing as well::
+ - you can install the requirements for testing as well::
-    pip install -r requirements.txt -r requirements-dev.txt -r requirements-testing.txt
 
-To reactivate a VENV just run:
+    pip install -r requirements-testing.txt
-   source .venv/bin/activate
+
+To deactivate the virtual environment, use ``deactivate``. Then to reactivate it, just run::
+
+    source .venv/bin/activate
 
 To see option for the Makefile run: `make`
 
 The project enforces a standardized formatting in the CI/CD pipeline. To ensure you have the correct formatting run::
+
     make checkformat
     
 To auto format any code use this::
+
     make format
 
 Testing
@@ -145,5 +151,5 @@ Note that django-helpdesk is distributed with 3rd party products which
 have their own licenses. See LICENSE.3RDPARTY for license terms for
 included packages.
 
-.. _note: http://docs.djangoproject.com/en/dev/ref/databases/#sqlite-string-matching
+.. _note: https://docs.djangoproject.com/en/dev/ref/databases/#substring-matching-and-case-sensitivity
 

demo/README.rst

@@ -24,15 +24,13 @@ Ideally, you'd use a virtualenv instead
 (see below for details).
 
 To use your system directory, from the top-level
-django-helpdesk directory, simply run:
+django-helpdesk directory, simply run::
 
     make rundemo
 
 Once the console gives a prompt that the HTTP
 server is listening, open your web browser
-and navigate to:
+and navigate to http://localhost:8080
-
-    localhost:8080
 
 You should see the django-helpdesk public web portal!
 
@@ -40,7 +38,7 @@ If you shut down the server, you can't immediately
 re-run the demo because the make commands would
 encounter problems trying to re-write the database.
 Instead, before running the demo, you will need
-to first clean the demo:
+to first clean the demo::
 
     sudo make distclean
 
@@ -53,7 +51,7 @@ want to use a virtualenv.
 
 If so, you might change the pip in the makefile
 to point to your virtualenv's pip instead
-before running:
+before running::
 
     make rundemo
 

demo/demodesk/config/settings.py

@@ -68,7 +68,7 @@ MIDDLEWARE = [
     'django.middleware.clickjacking.XFrameOptionsMiddleware',
 ]
 
-ROOT_URLCONF = 'demo.demodesk.config.urls'
+ROOT_URLCONF = 'demodesk.config.urls'
 
 TEMPLATES = [
     {
@@ -87,7 +87,7 @@ TEMPLATES = [
     },
 ]
 
-WSGI_APPLICATION = 'demo.demodesk.config.wsgi.application'
+WSGI_APPLICATION = 'demodesk.config.wsgi.application'
 
 
 # django-helpdesk configuration settings

docs/configuration.rst

@@ -13,7 +13,7 @@ Before django-helpdesk will be much use, you need to do some basic configuration
 
    Don't forget to set the relevant Django environment variables in your crontab::
 
-       */5 * * * * /path/to/helpdesksite/manage.py get_email
+    */5 * * * * /path/to/helpdesksite/manage.py get_email
 
    This will run the e-mail import every 5 minutes
 
@@ -32,13 +32,13 @@ Before django-helpdesk will be much use, you need to do some basic configuration
 
 4. If you wish to automatically escalate tickets based on their age, set up a cronjob to run the escalation command on a regular basis::
 
-       0 * * * * /path/to/helpdesksite/manage.py escalate_tickets
+    0 * * * * /path/to/helpdesksite/manage.py escalate_tickets
 
    This will run the escalation process hourly, using the 'Escalation Days' setting for each queue to determine which tickets to escalate.
 
 5. If you wish to exclude some days (eg, weekends) from escalation calculations, enter the dates manually via the Admin, or setup a cronjob to run a management command on a regular basis::
 
-       0 0 * * 0 /path/to/helpdesksite/manage.py create_escalation_exclusions --days saturday,sunday --escalate-verbosely
+    0 0 * * 0 /path/to/helpdesksite/manage.py create_escalation_exclusions --days saturday,sunday --escalate-verbosely
 
    This will, on a weekly basis, create exclusions for the coming weekend.
 
@@ -46,9 +46,9 @@ Before django-helpdesk will be much use, you need to do some basic configuration
 
 7. If you do not send mail directly from your web server (eg, you need to use an SMTP server) then edit your ``settings.py`` file so it contains your mail server details::
 
-       EMAIL_HOST = 'XXXXX'
+    EMAIL_HOST = 'XXXXX'
-       EMAIL_HOST_USER = 'YYYYYY@ZZZZ.PPP'
+    EMAIL_HOST_USER = 'YYYYYY@ZZZZ.PPP'
-       EMAIL_HOST_PASSWORD = '123456'
+    EMAIL_HOST_PASSWORD = '123456'
 
 8. If you wish to use SOCKS4/5 proxy with Helpdesk Queue email operations, install PySocks manually. Please note that mixing both SOCKS and non-SOCKS email sources for different queues is only supported under Python 2; on Python 3, SOCKS proxy support is all-or-nothing: either all queue email sources must use SOCKS or none may use it. If you need this functionality on Python 3 please `let us know <https://github.com/django-helpdesk/django-helpdesk/issues/new>`_.
 
@@ -88,6 +88,6 @@ You may add your own site specific navigation header to be included inside the <
 
 1. Create an override template in your project's templates directory::
 
-       helpdesk/custom_navigation_header.html
+    helpdesk/custom_navigation_header.html
 
 2. Update the contents to display your custom navigation.

docs/custom_fields.rst

@@ -3,6 +3,4 @@ Custom Fields
 
 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.
 
-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.
-
 Custom fields are relatively inefficient; you can search them, but this might degrade performance of your installation if you make use of custom fields. They can be useful for tracking extra information that your organisation needs but that isn't supported out of the box.

docs/custom_templates.rst

@@ -6,4 +6,3 @@ django-helpdesk supports custom HTML templates that can be styled with CSS.
 In particular, users can include a file named `helpdesk-customize.css` in their django project directory to provide CSS overrides easily.
 
 In general, entire HTML and CSS templates may be overriden by including a file of the same name in the project directory. Django automatically searches the project directory before searching for default templates included with django-helpdesk.
-

docs/iframe_submission.rst

@@ -1,5 +1,5 @@
 Ticket submission with embeded iframe
--------------------------------------
+=====================================
 
 Django-helpdesk associates an email address with each submitted ticket. If you integrate django-helpdesk directly into your django application, logged in users will automatically have their email address set when they visit the `/tickets/submit/` form. If you wish to pre-fill fields in this form, you can do so simply by setting the following query parameters:
 

docs/index.rst

@@ -16,18 +16,13 @@ Contents
    settings
    spam
    custom_fields
+   custom_templates
    api
    webhooks
    iframe_submission
    teams
    license
 
-
-How Does It Look?
------------------
-
-You can see a demo installation at http://django-helpdesk-demo.herokuapp.com/
-
 Quick Start
 -----------
 
@@ -72,5 +67,3 @@ Optionally, their access to view tickets, both on the dashboard and through sear
 Licensing
 ---------
 django-helpdesk is released under the BSD license, however it packages 3rd party applications which may be using a different license. More details can be found in the :doc:`license` documentation.
-
-

docs/install.rst

@@ -1,12 +1,12 @@
-.. _installation:
 Installation
 ============
 
 .. note:: 
 
-   For standalone installation, refer to the :doc:`standalone installation docs <standalone>`.
+    For standalone installation, refer to the :doc:`standalone installation docs <standalone>`.
 
-``django-helpdesk`` installation isn't difficult, but it requires you have a bit of existing know-how about Django.
+``django-helpdesk`` installation isn't difficult, but it requires you have a bit 
+of existing know-how about Django.
 
 
 Prerequisites
@@ -33,9 +33,12 @@ Installing using PIP
 Try using ``pip install django-helpdesk``. Go and have a beer to celebrate Python packaging.
 
 Checkout ``main`` branch from git (Cutting Edge)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you're planning on editing the code or just want to get whatever is the latest and greatest, you can clone the official Git repository with ``git clone git://github.com/django-helpdesk/django-helpdesk.git``. Each official release of ``django-helpdesk`` is tagged.
+If you're planning on editing the code or just want to get whatever is the latest 
+and greatest, you can clone the official Git repository with 
+``git clone git://github.com/django-helpdesk/django-helpdesk.git``. Each official 
+release of ``django-helpdesk`` is tagged.
 
 Copy the ``helpdesk`` folder into your ``PYTHONPATH`` or add it to your ``PYTHONPATH``.
 
@@ -54,100 +57,134 @@ If you're on a brand new Django installation, make sure you do a ``migrate``
 errors with trying to create User settings.
 
 1. Edit your ``settings.py`` file add the following entries:
-   - add ``helpdesk`` to the ``INSTALLED_APPS`` along with some other required entries in the ``django.contrib`` package.
    
-     An example of the core  ``INSTALLED_APPS`` requirements for this app are shown below::
+   - Add ``helpdesk`` to the ``INSTALLED_APPS`` along with some other required 
+     entries in the ``django.contrib`` package.
 
-     INSTALLED_APPS = (
+    An example of the core  ``INSTALLED_APPS`` requirements for this app 
-         'django.contrib.auth',
+    are shown below::
-         'django.contrib.contenttypes',
-         'django.contrib.sessions',
-         'django.contrib.sites',  # Required for determining domain url for use in emails
-         'django.contrib.admin',  # Required for helpdesk admin/maintenance
-         'django.contrib.humanize',  # Required for elapsed time formatting
-         'bootstrap4form', # Required for nicer formatting of forms with the default templates
-         'rest_framework',  # required for the API
-         'django_cleanup.apps.CleanupConfig',  # Remove this if you do NOT want to delete files on the file system when the associated record is deleted in the database
-         'helpdesk',  # This is us!
-     )
 
-   - Enable or disable Teams based ticket assignment by setting the boolean flag named ``HELPDESK_TEAMS_MODE_ENABLED`` to True or False.
+        INSTALLED_APPS = (
+            'django.contrib.auth',
+            'django.contrib.contenttypes',
+            'django.contrib.sessions',
+            'django.contrib.sites',  # Required for determining domain url for use in emails
+            'django.contrib.admin',  # Required for helpdesk admin/maintenance
+            'django.contrib.humanize',  # Required for elapsed time formatting
+            'bootstrap4form', # Required for nicer formatting of forms with the default templates
+            'rest_framework',  # required for the API
+            'django_cleanup.apps.CleanupConfig',  # Remove this if you do NOT want to delete files on the file system when the associated record is deleted in the database
+            'helpdesk',  # This is us!
+        )
+
+   - Enable or disable Teams based ticket assignment by setting the boolean flag named 
+     ``HELPDESK_TEAMS_MODE_ENABLED`` to ``True`` or ``False``.
    
      IMPORTANT NOTE: It is ENABLED by default if you do not set this flag to False
-     See the :doc::ref:`teams`. section for a detailed explanation of how to use teams mode.
+     See the :doc:`Working with teams<teams>` section for a detailed explanation of how to 
+     use teams mode.  
      Below is an example for disabling teams::
-       HELPDESK_TEAMS_MODE_ENABLED=False 
+
+        HELPDESK_TEAMS_MODE_ENABLED=False 
 
    - Your ``settings.py`` file should also define a ``SITE_ID``
    
-     This will allow multiple projects to share a single database, and is required by ``django.contrib.sites`` in Django 1.9+.
+     This will allow multiple projects to share a single database, and is 
-     If you aren't running multiple sites, you can simply add a default ``SITE_ID`` to ``settings.py``
+     required by ``django.contrib.sites`` in Django 1.9+.
+     If you aren't running multiple sites, you can simply add a default 
+     ``SITE_ID`` to ``settings.py``
+
      Below is an example for setting a default::
         
-     SITE_ID = 1
+        SITE_ID = 1
 
-2. Make sure django-helpdesk is accessible via ``urls.py``. Add the following lines to ``urls.py``::
+2. Make sure django-helpdesk is accessible via ``urls.py``. Add the 
+   following lines to ``urls.py``::
 
-     from django.conf.urls import include
+    from django.conf.urls import include
-     path('helpdesk/', include('helpdesk.urls')),
+    path('helpdesk/', include('helpdesk.urls')),
 
-   Note that you can change 'helpdesk/' to anything you like, such as 'support/' or 'help/'. If you want django-helpdesk to be available at the root of your site (for example at http://support.mysite.tld/) then the path line will be as follows::
+   Note that you can change 'helpdesk/' to anything you like, such as 
+   'support/' or 'help/'. If you want django-helpdesk to be available at 
+   the root of your site (for example at http://support.mysite.tld/) then 
+   the path line will be as follows::
 
-     path('', include('helpdesk.urls', namespace='helpdesk')),
+    path('', include('helpdesk.urls', namespace='helpdesk')),
 
-   This line will have to come *after* any other lines in your urls.py such as those used by the Django admin.
+   This line will have to come *after* any other lines in your urls.py such 
+   as those used by the Django admin.
 
-   Note that the `helpdesk` namespace is no longer required for Django 1.9+ and you can use a different namespace.
+   Note that the `helpdesk` namespace is no longer required for Django 1.9+ 
+   and you can use a different namespace.
    However, it is recommended to use the default namespace name for clarity.
 
 3. Create the required database tables.
 
    Migrate using Django migrations::
 
-     python manage.py migrate helpdesk
+    python manage.py migrate helpdesk
 
 4. Include your static files in your public web path::
 
-      python manage.py collectstatic
+    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::
+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::
 
-      chown www-data:www-data attachments/
+    chown www-data:www-data attachments/
-      chmod 700 attachments
+    chmod 700 attachments
 
-   (substitute www-data for the user / group that your web server runs as, eg 'apache' or 'httpd')
+   (substitute www-data for the user / group that your web server runs as, eg 
+   'apache' or 'httpd')
 
    If all else fails, you could ensure all users can write to it::
 
-      chmod 777 attachments/
+    chmod 777 attachments/
 
    But this is NOT recommended, especially if you're on a shared server.
 
-6. Ensure that your ``attachments`` folder has directory listings turned off, to ensure users don't download files that they are not specifically linked to from their tickets.
+6. Ensure that your ``attachments`` folder has directory listings turned off, 
+   to ensure users don't download files that they are not specifically linked 
+   to from their tickets.
 
-   If you are using Apache, put a ``.htaccess`` file in the ``attachments`` folder with the following content::
+   If you are using Apache, put a ``.htaccess`` file in the ``attachments`` 
+   folder with the following content::
 
-      Options -Indexes
+    Options -Indexes
 
    You will also have to make sure that ``.htaccess`` files aren't being ignored.
 
-   Ideally, accessing http://MEDIA_URL/helpdesk/attachments/ will give you a 403 access denied error.
+   Ideally, accessing http://MEDIA_URL/helpdesk/attachments/ will give you a 403 
+   access denied error.
 
-7. If you already have a view handling your logins, then great! If not, add the following to ``settings.py`` to get your Django installation to use the login view included in ``django-helpdesk``::
+7. If you already have a view handling your logins, then great! If not, add the 
+   following to ``settings.py`` to get your Django installation to use the login 
+   view included in ``django-helpdesk``::
 
-      LOGIN_URL = '/helpdesk/login/'
+    LOGIN_URL = '/helpdesk/login/'
 
    Alter the URL to suit your installation path.
 
 8. Load initial e-mail templates, otherwise you will not be able to send e-mail::
 
-        python manage.py loaddata emailtemplate.json
+    python manage.py loaddata emailtemplate.json
 
-9. If you intend on using local mail directories for processing email into tickets, be sure to create the mail directory before adding it to the queue in the Django administrator interface. The default mail directory is ``/var/lib/mail/helpdesk/``. Ensure that the directory has appropriate permissions so that your Django/web server instance may read and write files from this directory.
+9. If you intend on using local mail directories for processing email into tickets, 
+   be sure to create the mail directory before adding it to the queue in the 
+   Django administrator interface. The default mail directory is 
+   ``/var/lib/mail/helpdesk/``. Ensure that the directory has appropriate 
+   permissions so that your Django/web server instance may read and write 
+   files from this directory.
 
-   Note that by default, any mail files placed in your local directory will be permanently deleted after being successfully processed. It is strongly recommended that you take further steps to save emails if you wish to retain backups.
+   Note that by default, any mail files placed in your local directory will be 
+   permanently deleted after being successfully processed. It is strongly recommended 
+   that you take further steps to save emails if you wish to retain backups.
 
-   Also, be aware that if a disk error occurs and the local file is not deleted, the mail may be processed multiple times and generate duplicate tickets until the file is removed. It is recommended to monitor log files for ERRORS when a file is unable to be deleted.
+   Also, be aware that if a disk error occurs and the local file is not deleted, 
+   the mail may be processed multiple times and generate duplicate tickets until 
+   the file is removed. It is recommended to monitor log files for ERRORS when a 
+   file is unable to be deleted.
 
 Upgrading from previous versions
 --------------------------------

docs/license.rst

@@ -1,7 +1,7 @@
 License
 =======
 
-django-helpdesk is released under the terms of the BSD license. You must agree to these terms before installing or using django-helpdesk.::
+django-helpdesk is released under the terms of the BSD license. You must agree to these terms before installing or using django-helpdesk. ::
 
     Copyright (c) 2008, Ross Poulton (Trading as Jutda)
     Copyright (c) 2008-2021, django-helpdesk contributors
@@ -42,6 +42,7 @@ applications are included below.
 License for jQuery & jQuery UI
 ------------------------------
 ::
+
     Copyright (c) 2007 John Resig, http://jquery.com/
 
     Permission is hereby granted, free of charge, to any person obtaining
@@ -66,6 +67,7 @@ License for jQuery & jQuery UI
 License for jQuery UI 'Smoothness' theme
 ----------------------------------------
 ::
+    
     /*
      * jQuery UI screen structure and presentation
      * This CSS file was generated by ThemeRoller, a Filament Group Project for jQuery UI
@@ -76,6 +78,7 @@ License for jQuery UI 'Smoothness' theme
 License for akismet.py
 ----------------------
 ::
+
     Copyright (c) 2003-2009, Michael Foord
     All rights reserved.
     E-mail : fuzzyman AT voidspace DOT org DOT uk
@@ -112,6 +115,7 @@ License for akismet.py
 License for jqPlot
 ------------------
 ::
+
     Copyright (c) 2009 - 2010 Chris Leonello
 
     Permission is hereby granted, free of charge, to any person obtaining a copy

docs/settings.rst

@@ -22,6 +22,7 @@ First, django-helpdesk needs  ``django.core.context_processors.request`` activat
 
 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
 -------------------------
 
@@ -30,12 +31,13 @@ django-helpdesk has a built in ``UserSettings`` entity with per-user options tha
 If you want to override the default settings for your users, create ``HELPDESK_DEFAULT_SETTINGS`` as a dictionary in ``settings.py``. The default is below::
 
     HELPDESK_DEFAULT_SETTINGS = {
-            'use_email_as_submitter': True,
+        'use_email_as_submitter': True,
-            'email_on_ticket_assign': True,
+        'email_on_ticket_assign': True,
-            'email_on_ticket_change': True,
+        'email_on_ticket_change': True,
-            'login_view_ticketlist': True,
+        'login_view_ticketlist': True,
-            'tickets_per_page': 25
+        'tickets_per_page': 25
-            }
+    }
+
 
 Generic Options
 ---------------
@@ -87,7 +89,7 @@ These changes are visible throughout django-helpdesk
 
 - **VALID_EXTENSIONS** Valid extensions for file types that can be attached to tickets
 
-  **Default:** ``VALID_EXTENSIONS = ['.txt', '.asc', '.htm', '.html', '.pdf', '.doc', '.docx', '.odt', '.jpg', '.png', '.eml']
+  **Default:** ``VALID_EXTENSIONS = ['.txt', '.asc', '.htm', '.html', '.pdf', '.doc', '.docx', '.odt', '.jpg', '.png', '.eml']``
 
 - **QUEUE_EMAIL_BOX_UPDATE_ONLY** Only process mail with a valid tracking ID; all other mail will be ignored instead of creating a new ticket.
 
@@ -109,6 +111,7 @@ These changes are visible throughout django-helpdesk
 
   **Default:** ``HELPDESK_TICKETS_TIMELINE_ENABLED = True``
 
+
 Options shown on public pages
 -----------------------------
 
@@ -149,9 +152,9 @@ Options that change ticket updates
 - **HELPDESK_ALLOW_NON_STAFF_TICKET_UPDATE** Allow non-staff users to interact with tickets?
   Set to True to allow any authenticated user to manage tickets.
   You can also apply a custom authorisation logic for identifying helpdesk staff members, by setting this to a callable.
-  In that case, the value should be a function accepting the active user as a parameter and returning True if the user is considered helpdesk staff, e.g.
+  In that case, the value should be a function accepting the active user as a parameter and returning True if the user is considered helpdesk staff, e.g.::
 
-    lambda u: u.is_authenticated() and u.is_active and u.groups.filter(name='helpdesk_staff').exists()))
+    lambda u: u.is_authenticated() and u.is_active and u.groups.filter(name='helpdesk_staff').exists()
 
   **Default:** ``HELPDESK_ALLOW_NON_STAFF_TICKET_UPDATE = False``
 
@@ -203,36 +206,36 @@ Options that change ticket properties
 
   The **default** is below::
 
-        HELPDESK_TICKET_STATUS_CHOICES = (
+    HELPDESK_TICKET_STATUS_CHOICES = (
-            (HELPDESK_TICKET_OPEN_STATUS, _('Open')),
+        (HELPDESK_TICKET_OPEN_STATUS, _('Open')),
-            (HELPDESK_TICKET_REOPENED_STATUS, _('Reopened')),
+        (HELPDESK_TICKET_REOPENED_STATUS, _('Reopened')),
-            (HELPDESK_TICKET_RESOLVED_STATUS, _('Resolved')),
+        (HELPDESK_TICKET_RESOLVED_STATUS, _('Resolved')),
-            (HELPDESK_TICKET_CLOSED_STATUS, _('Closed')),
+        (HELPDESK_TICKET_CLOSED_STATUS, _('Closed')),
-            (HELPDESK_TICKET_DUPLICATE_STATUS, _('Duplicate')),
+        (HELPDESK_TICKET_DUPLICATE_STATUS, _('Duplicate')),
-        )
+    )
 
   If you wish to modify or introduce new status choices, you may add them like this::
         
-        # don't forget to import the gettext_lazy function at the begining of your settings file
+    # Don't forget to import the gettext_lazy function at the begining of your settings file
-        from django.utils.translation import gettext_lazy as _
+    from django.utils.translation import gettext_lazy as _
 
-        # explicitly define status list integer values
+    # Explicitly define status list integer values
-        HELPDESK_TICKET_OPEN_STATUS = 1
+    HELPDESK_TICKET_OPEN_STATUS = 1
-        HELPDESK_TICKET_REOPENED_STATUS = 2
+    HELPDESK_TICKET_REOPENED_STATUS = 2
-        HELPDESK_TICKET_RESOLVED_STATUS = 3
+    HELPDESK_TICKET_RESOLVED_STATUS = 3
-        HELPDESK_TICKET_CLOSED_STATUS = 4
+    HELPDESK_TICKET_CLOSED_STATUS = 4
-        HELPDESK_TICKET_DUPLICATE_STATUS = 5
+    HELPDESK_TICKET_DUPLICATE_STATUS = 5
-        HELPDESK_TICKET_FORKED_STATUS = 6
+    HELPDESK_TICKET_FORKED_STATUS = 6
 
-        # create the list with associated labels
+    # Create the list with associated labels
-        HELPDESK_TICKET_STATUS_CHOICES = (
+    HELPDESK_TICKET_STATUS_CHOICES = (
-            (HELPDESK_TICKET_OPEN_STATUS, _('Open')),
+        (HELPDESK_TICKET_OPEN_STATUS, _('Open')),
-            (HELPDESK_TICKET_REOPENED_STATUS, _('Reopened')),
+        (HELPDESK_TICKET_REOPENED_STATUS, _('Reopened')),
-            (HELPDESK_TICKET_RESOLVED_STATUS, _('Resolved')),
+        (HELPDESK_TICKET_RESOLVED_STATUS, _('Resolved')),
-            (HELPDESK_TICKET_CLOSED_STATUS, _('Closed')),
+        (HELPDESK_TICKET_CLOSED_STATUS, _('Closed')),
-            (HELPDESK_TICKET_DUPLICATE_STATUS, _('Duplicate')),
+        (HELPDESK_TICKET_DUPLICATE_STATUS, _('Duplicate')),
-            (HELPDESK_TICKET_FORKED_STATUS, _('Forked')),
+        (HELPDESK_TICKET_FORKED_STATUS, _('Forked')),
-        )
+    )
 
 - **HELPDESK_TICKET_OPEN_STATUSES** Define the list of statuses to be considered as a type of open status.
 
@@ -240,56 +243,58 @@ Options that change ticket properties
 
   If you have added the ``HELPDESK_TICKET_FORKED_STATUS`` status and wish to have django-helpdesk treat it as an open status choice, add it to the list of OPEN_STATUSES like this::
 
-        HELPDESK_TICKET_OPEN_STATUSES = (HELPDESK_TICKET_OPEN_STATUS,
+    HELPDESK_TICKET_OPEN_STATUSES = (HELPDESK_TICKET_OPEN_STATUS,
-                                         HELPDESK_TICKET_REOPENED_STATUS,
+                                        HELPDESK_TICKET_REOPENED_STATUS,
-                                         HELPDESK_TICKET_FORKED_STATUS)
+                                        HELPDESK_TICKET_FORKED_STATUS)
 
 - **HELPDESK_TICKET_STATUS_CHOICES_FLOW** Customize the allowed state changes depending on the current state.
 
   The **default** is below::
 
-        HELPDESK_TICKET_STATUS_CHOICES_FLOW = {
+    HELPDESK_TICKET_STATUS_CHOICES_FLOW = {
-            HELPDESK_TICKET_OPEN_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
+        HELPDESK_TICKET_OPEN_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
-            HELPDESK_TICKET_REOPENED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
+        HELPDESK_TICKET_REOPENED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
-            HELPDESK_TICKET_RESOLVED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
+        HELPDESK_TICKET_RESOLVED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
-            HELPDESK_TICKET_CLOSED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
+        HELPDESK_TICKET_CLOSED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
-            HELPDESK_TICKET_DUPLICATE_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
+        HELPDESK_TICKET_DUPLICATE_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
-        }
+    }
 
   If you wish to modify or have introduce new status choices, you may configure their status change flow like this::
 
-        # adding HELPDESK_TICKET_FORKED_STATUS to the other allowed states flow and defining its own flow
+    # Adding HELPDESK_TICKET_FORKED_STATUS to the other allowed states flow and defining its own flow
-        HELPDESK_TICKET_STATUS_CHOICES_FLOW = {
+    HELPDESK_TICKET_STATUS_CHOICES_FLOW = {
-            HELPDESK_TICKET_OPEN_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
+        HELPDESK_TICKET_OPEN_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
-            HELPDESK_TICKET_REOPENED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
+        HELPDESK_TICKET_REOPENED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
-            HELPDESK_TICKET_RESOLVED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
+        HELPDESK_TICKET_RESOLVED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
-            HELPDESK_TICKET_CLOSED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
+        HELPDESK_TICKET_CLOSED_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_CLOSED_STATUS,),
-            HELPDESK_TICKET_DUPLICATE_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
+        HELPDESK_TICKET_DUPLICATE_STATUS: (HELPDESK_TICKET_REOPENED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
-            HELPDESK_TICKET_FORKED_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
+        HELPDESK_TICKET_FORKED_STATUS: (HELPDESK_TICKET_OPEN_STATUS, HELPDESK_TICKET_FORKED_STATUS, HELPDESK_TICKET_RESOLVED_STATUS, HELPDESK_TICKET_CLOSED_STATUS, HELPDESK_TICKET_DUPLICATE_STATUS,),
-        }
+    }
 
 - **HELPDESK_TICKET_PRIORITY_CHOICES** Customize the priority choices for all tickets.
 
   The **default** is below::
 
-        HELPDESK_TICKET_PRIORITY_CHOICES = (
+    HELPDESK_TICKET_PRIORITY_CHOICES = (
-            (1, _('1. Critical')),
+        (1, _('1. Critical')),
-            (2, _('2. High')),
+        (2, _('2. High')),
-            (3, _('3. Normal')),
+        (3, _('3. Normal')),
-            (4, _('4. Low')),
+        (4, _('4. Low')),
-            (5, _('5. Very Low')),
+        (5, _('5. Very Low')),
-        )
+    )
+        
   If you have a new instance, you may override those settings but if you want to keep previous tickets priorities and add new choices, you may increment integer values like this::
 
-        HELPDESK_TICKET_PRIORITY_CHOICES = (
+    HELPDESK_TICKET_PRIORITY_CHOICES = (
-            (1, _('1. Critical')),
+        (1, _('1. Critical')),
-            (2, _('2. High')),
+        (2, _('2. High')),
-            (3, _('3. Normal')),
+        (3, _('3. Normal')),
-            (4, _('4. Low')),
+        (4, _('4. Low')),
-            (5, _('5. Very Low')),
+        (5, _('5. Very Low')),
-            (6, _('6. Cold')),
+        (6, _('6. Cold')),
-            (7, _('7. Hot')),
+        (7, _('7. Hot')),
-        )
+    )
+
 
 Time Tracking Options
 ---------------------
@@ -304,15 +309,15 @@ Time Tracking Options
   
   If HELPDESK_FOLLOWUP_TIME_SPENT_AUTO is ``True``, you may set open hours to remove off hours from 'time_spent'::
   
-        HELPDESK_FOLLOWUP_TIME_SPENT_OPENING_HOURS = {
+    HELPDESK_FOLLOWUP_TIME_SPENT_OPENING_HOURS = {
-            "monday": (8.5, 19),
+        "monday": (8.5, 19),
-            "tuesday": (8.5, 19),
+        "tuesday": (8.5, 19),
-            "wednesday": (8.5, 19),
+        "wednesday": (8.5, 19),
-            "thursday": (8.5, 19),
+        "thursday": (8.5, 19),
-            "friday": (8.5, 19),
+        "friday": (8.5, 19),
-            "saturday": (0, 0),
+        "saturday": (0, 0),
-            "sunday": (0, 0),
+        "sunday": (0, 0),
-        }
+    }
   
   Valid hour values must be set between 0 and 23.9999.
   In this example 8.5 is interpreted as 8:30AM, saturdays and sundays don't count.
@@ -323,7 +328,7 @@ Time Tracking Options
   
   This example removes Christmas and New Year's Eve in 2024::
 
-        HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_HOLIDAYS = ("2024-12-25", "2024-12-31",)
+    HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_HOLIDAYS = ("2024-12-25", "2024-12-31",)
 
 - **HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_STATUSES** List of ticket statuses to exclude from automatic follow-up 'time_spent' calculation.
 
@@ -331,15 +336,16 @@ Time Tracking Options
   
   This example will have follow-ups to resolved ticket status not to be counted in::
 
-        HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_STATUSES = (HELPDESK_TICKET_RESOLVED_STATUS,)
+    HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_STATUSES = (HELPDESK_TICKET_RESOLVED_STATUS,)
 
 - **HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_QUEUES** List of ticket queues slugs to exclude from automatic follow-up 'time_spent' calculation.
 
   **Default:** ``HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_QUEUES = ()``
   
-  This example will have follow-ups to ticket queue 'time-not-counting-queue' not to be counted in::
+  This example will have follow-ups excluded from time calculation if they belong to the queue with slug ``time-not-counting-queue``::
+
+    HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_QUEUES = ('time-not-counting-queue',)
 
-        HELPDESK_FOLLOWUP_TIME_SPENT_EXCLUDE_QUEUES = ('time-not-counting-queue',)
 
 Staff Ticket Creation Settings
 ------------------------------
@@ -348,6 +354,7 @@ Staff Ticket Creation Settings
 
   **Default:** ``HELPDESK_CREATE_TICKET_HIDE_ASSIGNED_TO = False``
 
+
 Staff Ticket View Settings
 ------------------------------
 
@@ -356,7 +363,6 @@ Staff Ticket View Settings
   **Default:** ``HELPDESK_ENABLE_PER_QUEUE_STAFF_PERMISSION = False``
 
 
-
 Default E-Mail Settings
 -----------------------
 
@@ -368,6 +374,7 @@ The following settings default to ``None`` but can be set as defaults, rather th
 - ``QUEUE_EMAIL_BOX_USER``
 - ``QUEUE_EMAIL_BOX_PASSWORD``
 
+
 Discontinued Settings
 ---------------------
 

docs/spam.rst

@@ -22,11 +22,10 @@ This service is free to use, within their terms and conditions.
 
 If you have either of these settings enabled, the spam filtering will be done automatically. If you have *both* settings configured, TypePad will be used instead of Akismet.
 
-
 Example
 ~~~~~~~
 
 A sample configuration in ``settings.py`` may be::
 
-   TYPEPAD_ANTISPAM_API_KEY = 'abc123'
+    TYPEPAD_ANTISPAM_API_KEY = 'abc123'
 

docs/standalone.rst

@@ -1,6 +1,5 @@
-==============================
 Django-Helpdesk Standalone Installation
-==============================
+=======================================
 
 Installation
 ------------
@@ -9,25 +8,25 @@ Installation
 
    .. code-block:: bash
    
-      git clone git@github.com:django-helpdesk/django-helpdesk.git
+    git clone git@github.com:django-helpdesk/django-helpdesk.git
 
 2. Go to the standalone helpdesk installation directory:
 
    .. code-block:: bash
    
-      cd django-helpdesk/standalone
+    cd django-helpdesk/standalone
 
 3. Execute the installation script:
    
    .. code-block:: bash
    
-      ./setup.sh
+    ./setup.sh
 
 4. Start the services:
 
    .. code-block:: bash
    
-      docker-compose up
+    docker-compose up
 
 Creating an Admin User
 ----------------------
@@ -36,25 +35,25 @@ Creating an Admin User
 
    .. code-block:: bash
    
-      docker ps
+    docker ps
 
 2. Execute into the `standalone-django-helpdesk-1` container:
 
    .. code-block:: bash
 
-      docker exec -it standalone-django-helpdesk-1 bash
+    docker exec -it standalone-django-helpdesk-1 bash
 
 3. Change directory to the application's root:
 
    .. code-block:: bash
    
-      cd /opt/django-helpdesk/standalone
+    cd /opt/django-helpdesk/standalone
 
 4. Create a superuser:
 
    .. code-block:: bash
    
-      python3 manage.py createsuperuser
+    python3 manage.py createsuperuser
 
 5. Visit `localhost:80` in your browser to access the server. Navigate to the `/admin` URL to set up new users. Ensure to configure the "Site" in the admin section for ticket email URLs to function correctly.
 
@@ -71,16 +70,16 @@ Configuration for Production Use
 
    .. code-block:: html
    
-      <style>
+    <style>
-      .navbar-brand {
+    .navbar-brand {
-          background: url("https://www.libertyaces.com/files/liberty-logo.png") no-repeat;
+        background: url("https://www.libertyaces.com/files/liberty-logo.png") no-repeat;
-          background-size: auto;
+        background-size: auto;
-          width: 320px;
+        width: 320px;
-          background-size: contain;
+        background-size: contain;
-          height: 40px;
+        height: 40px;
-          text-align: right;
+        text-align: right;
-      }
+    }
-      </style>
+    </style>
 
 AWS SES Email Configuration
 ---------------------------
@@ -89,23 +88,22 @@ An example `local_settings` configuration for utilizing AWS SES for email:
 
 .. code-block:: python
 
+    from .settings import *
+    import os
 
-   from .settings import *
+    DEFAULT_FROM_EMAIL = "support@bitswan.space"
-   import os
+    SERVER_EMAIL = "support@bitswan.space"
-
+    AWS_ACCESS_KEY_ID = os.environ.get("AWS_ACCESS_KEY_ID")
-   DEFAULT_FROM_EMAIL = "support@bitswan.space"
+    EMAIL_BACKEND = "django_ses.SESBackend"
-   SERVER_EMAIL = "support@bitswan.space"
+    AWS_SES_REGION_NAME = "eu-west-1"
-   AWS_ACCESS_KEY_ID = os.environ.get("AWS_ACCESS_KEY_ID")
+    AWS_SES_REGION_ENDPOINT = "email.eu-west-1.amazonaws.com"
-   EMAIL_BACKEND = "django_ses.SESBackend"
+    AWS_SECRET_ACCESS_KEY = os.environ.get("AWS_SECRET_ACCESS_KEY")
-   AWS_SES_REGION_NAME = "eu-west-1"
-   AWS_SES_REGION_ENDPOINT = "email.eu-west-1.amazonaws.com"
-   AWS_SECRET_ACCESS_KEY = os.environ.get("AWS_SECRET_ACCESS_KEY")
 
 To integrate `django-ses`, bindmount a file to `/opt/extra-dependencies.txt` containing:
 
 .. code-block:: text
 
-   django-ses
+    django-ses
 
 Make sure you update the `docker.env` file with the necessary secrets.
 
@@ -127,10 +125,9 @@ Working from the previous SES example we add the following to `local_settings`:
 
     DEFAULT_FILE_STORAGE = "storages.backends.s3boto3.S3Boto3Storage"
 
-
 To integrate `django-ses`, bindmount a file to `/opt/extra-dependencies.txt` containing:
 
 .. code-block:: text
 
-   django-storages
+    django-storages
-   boto3
+    boto3

docs/teams.rst

@@ -1,4 +1,5 @@
 .. _teams:
+
 Working with teams and larger organizations
 ===========================================
 
@@ -11,6 +12,7 @@ If you are embedding the helpdesk app into your own apps, it is possible that th
 
 How It Works
 ------------
+
 Rather than assigning tickets to teams directly, django-helpdesk allows you assign tickets to knowledge-base items and then assign knowledge base items to teams.
 
 Knowledge-base items can be in either public or private knowledge-base categories, so this organizational structure need not have any influence on the external appearance of your public helpdesk web portal.
@@ -21,22 +23,28 @@ You can assign a knowledge-base item to a team on the Helpdesk admin page.
 
 Once you have set up teams. Unassigned tickets which are associated with a knowledge-base item will only be shown on the dashboard to those users who are members of the team which is associated with that knowledge-base item.
 
+
 Implementing Custom Teams Functionality
---------------------------------
+---------------------------------------
+
 If you want to use a different team app or implement your own team based app, you can hook it into Helpdesk using the following 3 settings:
+
 ``HELPDESK_TEAMS_MODEL``: point this to the model that defines a team in your custom implementation
 ``HELPDESK_TEAMS_MIGRATION_DEPENDENCIES``: set this to an array of migration(s) that are required to have run that will ensure the link that will be added as defined in the HELPDESK_TEAMS_MODEL will be available as a model to Helpdesk
 ``HELPDESK_KBITEM_TEAM_GETTER``: the method that will be called that must return a list of users who belong to a given team
 
 
 Configuring Teams Functionality
------------------------------
+-------------------------------
+
 Teams functionality is enabled by default but can be disabled using this entry in your ``settings.py``::
-      HELPDESK_TEAMS_MODE_ENABLED=False 
+
+    HELPDESK_TEAMS_MODE_ENABLED=False 
 
 If you do not disable teams functionality then you must add additional apps into the ``INSTALLED_APPS`` in your ``settings.py``.
 The following can be pasted into your settings.py BELOW the ``INSTALLED_APPS`` definition::
-INSTALLED_APPS.extend([
+
+    INSTALLED_APPS.extend([
         'account',  # Required by pinax-teams
         'pinax.invitations',  # required by pinax-teams
         'pinax.teams',  # team support
@@ -45,7 +53,10 @@ INSTALLED_APPS.extend([
 
 Alternatively just add the 4 apps listed above into the ``INSTALLED_APPS``.
 
+
 Disabling Teams Functionality
 -----------------------------
+
 Teams functionality is enabled by default but can be disabled using this entry in your ``settings.py``::
-      HELPDESK_TEAMS_MODE_ENABLED=False 
+
+    HELPDESK_TEAMS_MODE_ENABLED=False 

docs/upgrade.rst

@@ -3,7 +3,6 @@ Upgrading
 
 Your ``django-helpdesk`` installation can be upgraded to the latest version using the release notes below.
 
-
 Prerequisites
 -------------
 
@@ -22,13 +21,13 @@ The tips below are based on modifications of the original installation instructi
 
 - Under `INSTALLED_APPS`, `bootstrapform` needs to be replaced with `bootstrap4form`
 
-- Unless turning off `pinax_teams`, add the following to `INSTALLED_APPS` for `pinax_teams`:
+- Unless turning off `pinax_teams`, add the following to `INSTALLED_APPS` for `pinax_teams`::
-  ```
+
-  "account",
+    "account",
-  "pinax.invitations",
+    "pinax.invitations",
-  "pinax.teams",
+    "pinax.teams",
-  "reversion",
+    "reversion",
-  ```
+
   
 - If using `send_templated_mail`, then it now needs to be imported from `helpdesk.templated_email`