more docs

diff --git a/doc/source/urlopener.rst b/doc/source/urlopener.rst
deleted file mode 100644 (file)
index 6f9e16d..0000000
--- a/doc/source/urlopener.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-URLOpener\r
-=========\r
-\r
-.. automodule:: jenkinsapi.utils.urlopener\r
-   :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 (file)
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 (file)
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')