UPDATE Usage.rst & rt.rst

read-the-docs/source/Usage.rst

@@ -4,7 +4,7 @@ Usage
 **The general usage workflow for creating new tickets is:**
 
 **Introduction**
-################
+****************
 
 Create a JiraTicket, RTTicket, RedmineTicket, BugzillaTicket
 or ServiceNowTicket object with ``<url>``, ``<project>`` and ``<auth>``. This
@@ -16,7 +16,7 @@ authentication (JIRA and RT), the ``<auth>`` parameter should contain
 
 
 **How to**
-##########
+**********
 
 - Create a ticket with the ``create()`` method. This sets the ``ticket_id``
   instance variable, allowing you to perform more tasks on the ticket.
@@ -39,8 +39,8 @@ authentication (JIRA and RT), the ``<auth>`` parameter should contain
 
 - Close ticket Requests session with ``close_requests_session()``.
 
-**Contd..**
-###########
+Contd..
+***********
 
 There is also a ``set_ticket_id()`` method for a Ticket object. This is
 useful if you are working with a Ticket object that already has the
@@ -49,7 +49,8 @@ on a separate ticket. Instead of creating a new Ticket object, you can
 simply pass an existing ``<ticket_id>`` in to the ``set_ticket_id()``
 method to begin working on another ticket.
 
-**How to:**
+How to:
+*******
 
 - To return the current Ticket object's ticket_id or ticket_url, use the ``get_ticket_id()`` or ``get_ticket_url()`` methods.
 

read-the-docs/source/rt.rst

@@ -1,4 +1,4 @@
-rt
+RT
 ====
 
 This document contains information on the methods available when working
@@ -113,3 +113,108 @@ Attaches a file to a RT ticket.
 
     t.add_attachment('filename.txt')
 
+
+Examples
+^^^^^^^^
+
+Create RTTicket object
+----------------------
+
+Authenticate through HTTP Basic Authentication:
+
+.. code:: python
+
+    >>> from ticketutil.rt import RTTicket
+    >>> t = RTTicket(<rt_url>,
+                     <project_queue>,
+                     auth=('username', 'password'))
+
+Authenticate through Kerberos after running ``kinit``:
+
+.. code:: python
+
+    >>> from ticketutil.rt import RTTicket
+    >>> t = RTTicket(<rt_url>,
+                     <project_queue>,
+                     auth='kerberos')
+
+You should see the following response:
+
+::
+
+    INFO:requests.packages.urllib3.connectionpool:Starting new HTTPS connection (1): <rt_url>
+    INFO:root:Successfully authenticated to RT
+
+You now have a ``RTTicket`` object that is associated with the
+``<project_queue>`` queue.
+
+Some example workflows are found below. Notice that the first step is to
+create a RTTicket object with a url and project queue (and with a ticket
+id when working with existing tickets), and the last step is closing the
+Requests session with ``t.close_requests_session()``.
+
+When creating a RT ticket, ``subject`` and ``text`` are required
+parameters. Also, the Reporter is automatically filled in as the current
+kerberos principal.
+
+Note: The tested parameters for the create() and edit() methods are
+found in the docstrings in the code and in the docs folder. Any other
+ticket field can be passed in as a keyword argument, but be aware that
+the value for non-tested fields or custom fields may be in a
+non-intuitive format. See RT's REST API documentation for more
+information: https://rt-wiki.bestpractical.com/wiki/REST
+
+Create and update RT ticket
+---------------------------
+
+.. code:: python
+
+    from ticketutil.rt import RTTicket
+
+    # Create a ticket object and pass the url and project queue in as strings.
+    t = RTTicket(<rt_url>,
+                 <project_queue>,
+                 auth='kerberos')
+
+    # Create a ticket and perform some common ticketing operations.
+    t.create(subject='Ticket subject',
+             text='Ticket text',
+             priority='5',
+             owner='username@mail.com',
+             cc='username@mail.com,
+             admincc=['username@mail.com', 'username2@mail.com'])
+    t.add_comment('Test Comment')
+    t.edit(priority='4',
+           cc='username1@mail.com')
+    t.add_attachment('file_to_attach.txt')
+    t.change_status('Resolved')
+
+    # Close Requests session.
+    t.close_requests_session()
+
+
+Update existing RT tickets
+--------------------------
+
+.. code:: python
+
+    from ticketutil.rt import RTTicket
+
+    # Create a ticket object and pass the url, project queue, and ticket id in as strings.
+    t = RTTicket(<rt_url>,
+                 <project_queue>,
+                 auth='kerberos',
+                 ticket_id=<ticket_id>)
+
+    # Perform some common ticketing operations.
+    t.add_comment('Test Comment')
+    t.edit(priority='4',
+           cc='username@mail.com')
+
+    # Work with a different ticket.
+    t.set_ticket_id(<new_ticket_id>)
+    t.change_status('Resolved')
+
+    # Close Requests session.
+    t.close_requests_session()
+