Adding documentation for the Github package.

docs/manual/book.xml

@@ -6,6 +6,8 @@
 
   <xi:include href="chapters/preface.xml" />
 
+  <xi:include href="chapters/github.xml" />
+
   <xi:include href="chapters/testing.xml" />
 
   <xi:include href="appendices/changelog.xml" />

docs/manual/chapters/github.xml

@@ -0,0 +1,100 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xml:id="preface" xmlns="http://docbook.org/ns/docbook" xmlns:ns5="http://www.w3.org/1999/xhtml"
+         xmlns:ns4="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1998/Math/MathML"
+         xmlns:ns2="http://www.w3.org/1999/xlink" xmlns:ns="http://docbook.org/ns/docbook">
+  <title>JGithub</title>
+
+  <section>
+    <title>Using the Github Package</title>
+
+    <para>The Github package is designed to be a straightforward interace for
+    working with Github. It is based on version 3 of the Github API. You can
+    find documentation on the API at <link linkend="???"><ulink
+    url="http://developer.github.com/v3/">http://developer.github.com/v3/.</ulink></link></para>
+
+    <para>JGithub is built upon the JHttp package which provides an easy way
+    to consume URLs and web services in a transport independent way. JHttp
+    currently supports streams, sockets and CURL. It is possible to create a
+    custom context and inject it into the JGithub class if one so
+    desires.</para>
+
+    <para></para>
+
+    <section>
+      <title>Instantiating JGithub</title>
+
+      <para>Instantiating JGithub is easy:</para>
+
+      <programlisting>$github = new JGithub;</programlisting>
+
+      <para>This creates a basic JGithub object that can be used to access
+      publically availabe resources on github.com.</para>
+
+      <para>Sometimes it is necessary to specify additional options. This can
+      be done by injecting in a JRegistry object with your preferred
+      options:<programlisting>$options = new JRegistry;
+$options-&gt;set('api.username', 'github_username');
+$options-&gt;set('api.password', 'github_password');
+
+$github = new JGithub($options);</programlisting></para>
+    </section>
+
+    <section>
+      <title>Accessing the JGithub APIs</title>
+
+      <para>The Github package is still incomplete, but there are four object
+      APIs that have currently been implemented:<simplelist>
+          <member>Gists</member>
+
+          <member>Issues</member>
+
+          <member>References</member>
+
+          <member>Pull Requests</member>
+        </simplelist></para>
+
+      <para>Once a JGithub object has been created, it is simple to use it to
+      access Github:<programlisting>$pullRequests = $github-&gt;pulls-&gt;getList('joomla', 'joomla-platform');</programlisting>This
+      will retrieve a list of all open pull requests in the specified
+      repository.</para>
+    </section>
+
+    <section>
+      <title>A More Complete Example</title>
+
+      <para>See below for an example demonstrating more of the JGithub
+      package:<programlisting>$options = new JRegistry;
+$options-&gt;set('api.username', 'github_username');
+$options-&gt;set('api.password', 'github_password');
+$options-&gt;set('api.url', 'http://myhostedgithub.example.com');
+
+$github = new JGithub($options);
+
+// get a list of all the user's issues
+$issues = $github-&gt;issues-&gt;getList();
+
+$issueSummary = array();
+
+foreach ($issues AS $issue)
+{
+    $issueSummary[] = '+ ' . $issue-&gt;title;
+}
+
+$summary = implode("\n", $issueSummary);
+
+$github-&gt;gists-&gt;create(array('issue_summary.txt' =&gt; $summary));</programlisting></para>
+    </section>
+
+    <section>
+      <title>More Information</title>
+
+      <para>The following resources contain more information:<simplelist>
+          <member><ulink url="http://api.joomla.org">Joomla! API
+          Reference</ulink></member>
+
+          <member><ulink url="http://developer.github.com">Github API
+          Reference</ulink></member>
+        </simplelist></para>
+    </section>
+  </section>
+</chapter>