Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Adding documentation for the Github package. #559

Merged
merged 1 commit into from

3 participants

@ianmacl

A short write up on how to use the Github package.

@joomla-jenkins
Collaborator

Unit testing complete. There were 0 failures and 0 errors from 1872 tests and 11090 assertions.
Checkstyle analysis reported 235 warnings and 0 errors.

@robschley robschley merged commit 548e35c into joomla:staging
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Nov 26, 2011
  1. @ianmacl
This page is out of date. Refresh to see the latest.
Showing with 102 additions and 0 deletions.
  1. +2 −0  docs/manual/book.xml
  2. +100 −0 docs/manual/chapters/github.xml
View
2  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" />
View
100 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>
Something went wrong with that request. Please try again.