Merge branch 'feature/docs-update' into develop

Author: vimishor

README.md

@@ -26,7 +26,7 @@ Simple Bitbucket API wrapper for PHP >= 5.3.2.
 
 ## Documentation
 
-See the `docs` directory for more detailed documentation.
+See [http://gentlero.bitbucket.org/bitbucket-api/](http://gentlero.bitbucket.org/bitbucket-api/) for more detailed documentation.
 
 ## License
 

docs/Home.md

@@ -0,0 +1,51 @@
+---
+layout: default
+permalink: /examples/authentication.html
+title: Authentication
+---
+
+# Authentication
+
+Although you can access any public data without authentication, you need to authenticate before you can access certain features like
+(_but not limited to_) accessing data from a private repository, or give access to a repository.
+Bitbucket provides Basic and OAuth authentication.
+
+### Basic authentication
+To use basic authentication, you need to attach `BasicAuthListener` to http client with your username and password.
+
+  ```php
+  $user = new Bitbucket\API\User();
+  $user->getClient()->addListener(
+      new Bitbucket\API\Http\Listener\BasicAuthListener($bb_user, $bb_pass)
+  );
+
+  // now you can access protected endpoints as $bb_user
+  $response = $user->get();
+  ```
+
+### OAuth authorization
+This library comes with a `OAuthListener` which will sign all requests for you. All you need to do is to attach the listener to
+http client with oauth credentials before making a request.
+
+  ```php
+  // OAuth 1-legged example
+  // You can create a new consumer at: https://bitbucket.org/account/user/<username or team>/api
+  $oauth_params = array(
+      'oauth_consumer_key'      => 'aaa',
+      'oauth_consumer_secret'   => 'bbb'
+  );
+
+  $user = new Bitbucket\API\User;
+  $user->getClient()->addListener(
+      new Bitbucket\API\Http\Listener\OAuthListener($oauth_params)
+  );
+
+  // now you can access protected endpoints as consumer owner
+  $response = $user->get();
+  ```
+
+----
+
+#### Related:
+  * [Authentication @ BB Wiki](https://confluence.atlassian.com/display/BITBUCKET/Use+the+Bitbucket+REST+APIs#UsetheBitbucketRESTAPIs-Authentication)
+  * [OAuth on Bitbucket @ BB Wiki](https://confluence.atlassian.com/display/BITBUCKET/OAuth+on+Bitbucket)

docs/authentication.md

@@ -1,46 +1,58 @@
-## Group Privileges
+---
+layout: default
+permalink: /examples/group-privileges.html
+title: Group Privileges
+---
+
+# Group Privileges
 
-----
 Manages a group's repository permissions.
 
 ### Prepare
+
 ```php
 $privileges = new Bitbucket\API\User();
 $privileges->setCredentials( new Bitbucket\API\Authentication\Basic($bb_user, $bb_pass) );
 ```
 
 ### Get a list of privileged groups
+
 ```php
 $groups = $privileges->groups($account_name);
 ```
 
 ### Get a list of privileged groups for a repository
+
 ```php
 $groups = $privileges->repository($account_name, $repo_slug);
 ```
 
 ### Gets the privileges of a group on a repository.
+
 ```php
 $group = $privileges->group($account_name, $repo_slug, $group_owner, $group_slug);
 ```
 
 ### Get a list of the repositories on which a particular privilege group appears.
+
 ```php
 $repos = $privileges->repositories($account_name, $group_owner, $group_slug);
 ```
 
 ### Grant group privileges on a repository.
+
 ```php
 $privileges->grant($account_name, $repo_slug, $group_owner, $group_slug, 'read');
 ```
 
 ### Delete group privileges from a repository
+
 ```php
 $privileges->delete($account_name, $repo_slug, $group_owner, $group_slug);
 ```
 
 ----
 
 #### Related:
-  * [Authentication](authentication.md)
+  * [Authentication]({{ site.url }}/examples/authentication.html)
   * [BB Wiki](https://confluence.atlassian.com/display/BITBUCKET/group-privileges+Endpoint#group-privilegesEndpoint-Overview)

docs/examples/authentication.md

@@ -1,6 +1,11 @@
-## Groups
+---
+layout: default
+permalink: /examples/groups.html
+title: Groups
+---
+
+# Groups
 
-----
 Provides functionality for querying information about groups, creating new ones, updating memberships, and deleting them.
 
 ### Prepare:
@@ -42,6 +47,6 @@ $groups->delete($account_name, 'testers');
 ----
 
 #### Related:
-  * [Authentication](authentication.md)
-  * [Group members](groups/members.md)
+  * [Authentication](authentication.html)
+  * [Group members](groups/members.html)
   * [BB Wiki](https://confluence.atlassian.com/display/BITBUCKET/groups+Endpoint)

docs/group-privileges.md renamed to docs/examples/group-privileges.md

@@ -1,7 +1,12 @@
-## Group members
+---
+layout: default
+permalink: /examples/groups/members.html
+title: Group members
+---
 
-----
-Manage group members.
+# Group members
+
+Manage members of a group.
 
 ### Prepare:
 ```php
@@ -27,6 +32,6 @@ $group->members()->delete($account_name, 'developers', 'miriam');
 ----
 
 #### Related:
-  * [Authentication](authentication.md)
-  * [Groups](../groups.md)
+  * [Authentication]({{ site.url }}/examples/authentication.html)
+  * [Groups]({{ site.url }}/examples/groups.html)
   * [BB Wiki](https://confluence.atlassian.com/display/BITBUCKET/groups+Endpoint)

docs/groups.md renamed to docs/examples/groups.md

@@ -0,0 +1,61 @@
+---
+layout: default
+permalink: /examples/
+title: Examples
+---
+
+# Usage examples
+
+**TIP:** Although all examples from this documentation are instantiating each class, a single point of entry is also available:
+
+  ```php
+  $bitbucket = new \Bitbucket\API\Api();
+  $bitbucket->getClient()->addListener(
+      new \Bitbucket\API\Http\Listener\BasicAuthListener('username', 'password')
+  );
+
+  /** @var \Bitbucket\API\User $user */
+  $user = $bitbucket->api('User');
+
+  /** @var \Bitbucket\API\Repositories\Issues $issues */
+  $issues = $bitbucket->api('Repositories\Issues');
+  ```
+
+### Available examples
+
+  - [Authentication](authentication.html)
+  - [Group privileges](group-privileges.html)
+  - [Groups](groups.html)
+  - [Invitations](invitations.html)
+  - [Privileges](privileges.html)
+  - [Repositories](repositories.html)
+    - [Branch restrictions](repositories/branch-restrictions.html)
+    - [Changesets](repositories/changesets.html)
+      - [Comments](repositories/changesets/comments.html)
+    - [Commits](repositories/commits.html)
+      - [Comments](repositories/commits/comments.html)
+    - [Deploy keys](repositories/deploy-keys.html)
+    - [Events](repositories/events.html)
+    - [Followers](repositories/followers.html)
+    - [Issues](repositories/issues.html)
+      - [Comments](repositories/issues/comments.html)
+      - [Components](repositories/issues/components.html)
+      - [Milestones](repositories/issues/milestones.html)
+      - [Versions](repositories/issues/versions.html)
+    - [Links](repositories/links.html)
+    - [Pull requests](repositories/pull-requests.html)
+      - [Comments](repositories/pull-requests/comments.html)
+    - [Repository](repositories/repository.html)
+    - [Services](repositories/services.html)
+    - [Src](repositories/src.html)
+    - [Wiki](repositories/wiki.html)
+  - [Teams](teams.html)
+  - [User](user.html)
+    - [Repositories](user/repositories.html)
+  - [Users](users.html)
+    - [Account](users/account.html)
+    - [Emails](users/emails.html)
+    - [Invitations](users/invitations.html)
+    - [OAuth](users/oauth.html)
+    - [Privileges](users/privileges.html)
+    - [SSH keys](users/ssh-keys.html)

docs/groups/members.md renamed to docs/examples/groups/members.md

@@ -1,21 +1,28 @@
-## Invitations
+---
+layout: default
+permalink: /examples/invitations.html
+title: Invitations
+---
+
+# Invitations
 
-----
 Allows repository administrators to send email invitations to grant read, write, or admin privileges to a repository.
 
 ### Prepare:
+
 ```php
 $invitation = new Bitbucket\API\Invitations();
 $invitation->setCredentials( new Bitbucket\API\Authentication\Basic($bb_user, $bb_pass) );
 ```
 
 ### Send invitation:
+
 ```php
 $invitation->send($account_name, $repo_slug, 'user@example.com', 'read');
 ```
 
 ----
 
 #### Related:
-  * [Authentication](authentication.md)
+  * [Authentication]({{ site.url }}/examples/authentication.html)
   * [BB Wiki](https://confluence.atlassian.com/display/BITBUCKET/invitations+Endpoint#invitationsEndpoint-Overview)