From 87d57df7ffcd04bf6d7fa31c1a0ad4e4cbd5f327 Mon Sep 17 00:00:00 2001
From: salimfadhley <sal@stodge.org>
Date: Wed, 19 Jun 2013 00:47:01 +0100
Subject: [PATCH] more docs

---
 doc/source/urlopener.rst                           |  5 -----
 doc/source/using_jenkinsapi.rst                    | 24 ++++++++++++++++++++++
 .../get_version_info_from_last_good_build.py       | 13 ++++++++++++
 3 files changed, 37 insertions(+), 5 deletions(-)
 delete mode 100644 doc/source/urlopener.rst
 create mode 100644 doc/source/using_jenkinsapi.rst
 create mode 100644 examples/how_to/get_version_info_from_last_good_build.py

diff --git a/doc/source/urlopener.rst b/doc/source/urlopener.rst
deleted file mode 100644
index 6f9e16d..0000000
--- a/doc/source/urlopener.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-URLOpener
-=========
-
-.. automodule:: jenkinsapi.utils.urlopener
-   :members:
\ No newline at end of file
diff --git a/doc/source/using_jenkinsapi.rst b/doc/source/using_jenkinsapi.rst
new file mode 100644
index 0000000..b708280
--- /dev/null
+++ b/doc/source/using_jenkinsapi.rst
@@ -0,0 +1,24 @@
+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
+-------------------------------------------------------------
+
+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.::
+
+    from jenkinsapi.jenkins import Jenkins
+
+    def getSCMInfroFromLatestGoodBuild(url, jobName, username=None, password=None):
+        J = Jenkins(url, username, password)
+        job = J[jobName]
+        lgb = job.get_last_good_build()
+        return lgb.get_revision()
+
+    if __name__ == '__main__':
+        print getSCMInfroFromLatestGoodBuild('http://localhost:8080', 'fooJob')
+
+When used with the Git source-control system line 20 will print out something like '8b4f4e6f6d0af609bb77f95d8fb82ff1ee2bba0d' - which looks suspiciously like a Git revision number.
+
+
diff --git a/examples/how_to/get_version_info_from_last_good_build.py b/examples/how_to/get_version_info_from_last_good_build.py
new file mode 100644
index 0000000..433574e
--- /dev/null
+++ b/examples/how_to/get_version_info_from_last_good_build.py
@@ -0,0 +1,13 @@
+"""
+Extract version information from the latest build.
+"""
+from jenkinsapi.jenkins import Jenkins
+
+def getSCMInfroFromLatestGoodBuild(url, jobName, username=None, password=None):
+    J = Jenkins(url, username, password)
+    job = J[jobName]
+    lgb = job.get_last_good_build()
+    return lgb.get_revision()
+
+if __name__ == '__main__':
+    print getSCMInfroFromLatestGoodBuild('http://localhost:8080', 'fooJob')
-- 
2.7.4