From: salimfadhley <sal@stodge.org>
Date: Tue, 18 Jun 2013 23:47:01 +0000 (+0100)
Subject: more docs
X-Git-Tag: v0.2.23~141
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=f0555f2a3d6ed0b845d7876367e53821c6c59fc9;p=tools%2Fpython-jenkinsapi.git

more docs
---

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')