Add a few Jenkins API usage examples

Add following examples showing usage of Jenkins API:
* Get Jenkins version, Get Job details, Enable/disable a job

diff --git a/doc/source/using_jenkinsapi.rst b/doc/source/using_jenkinsapi.rst
index b708280..7cedf5b 100644 (file)
--- a/doc/source/using_jenkinsapi.rst
+++ b/doc/source/using_jenkinsapi.rst
@@ -3,7 +3,60 @@ Using Jenkins API
 
 JenkinsAPI lets you query the state of a running Jenkins server. It also allows you to change configuration and automate minor tasks on nodes and jobs.
 
-Example 1: Getting version information from a completed build
+Example 1: Get version of Jenkins
+---------------------------------
+::
+ 
+    from jenkinsapi.jenkins import Jenkins
+    
+    def get_server_instance():
+        jenkins_url = 'http://jenkins_host:8080'
+        server = Jenkins(jenkins_url, username = 'foouser', password = 'foopassword')
+        return server
+    
+    if __name__ == '__main__':
+        print get_server_instance().version
+
+The above code prints version of Jenkins running on the host *jenkins_host*.
+
+From Jenkins vesion 1.426 onward one can specify an API token instead of your real password while authenticating the user against Jenkins instance. Refer to the the Jenkis wiki page 
+`Authenticating scripted clients <https://wiki.jenkins-ci.org/display/JENKINS/Authenticating+scripted+clients>`_
+for details about how a user can generate an API token. Once you have API token you can pass the API token instead of real password while creating an Jenkins server instance using Jenkins API.
+
+Example 2: Get details of jobs running on Jenkins server
+--------------------------------------------------------
+::
+ 
+    """Get job details of each job that is running on the Jenkins instance"""
+    def get_job_details():
+        # Refer Example #1 for definition of function 'get_server_instance'
+        server = get_server_instance()
+        for j in server.get_jobs():
+            job_instance = server.get_job(j[0])
+            print 'Job Name:%s' %(job_instance.name)
+            print 'Job Description:%s' %(job_instance.get_description())
+            print 'Is Job running:%s' %(job_instance.is_running())
+            print 'Is Job enabled:%s' %(job_instance.is_enabled())
+
+Example 3: Disable/Enable a Jenkins Job
+---------------------------------------
+
+::
+ 
+    """Disable a Jenkins job"""
+    def disable_job():
+        # Refer Example #1 for definition of function 'get_server_instance'
+        server = get_server_instance()
+        job_name = 'nightly-build-job'
+        if (server.has_job(job_name)):
+            job_instance = server.get_job(job_name)
+            job_instance.disable()
+            print 'Name:%s,Is Job Enabled ?:%s' %(job_name,job_instance.is_enabled())
+            
+Use the call ``job_instance.enable()`` to enable a Jenkins Job.
+
+
+Example 4: Getting version information from a completed build
 -------------------------------------------------------------
 
 This is a typical use of JenkinsAPI - it was the very first use I had in mind when the project was first built: In a continuous-integration environment you want to be able to programatically detect the version-control information of the last succsessful build in order to trigger some kind of release process.::