Convert release notes to our documentation

Also allow the documentation to successfully build by stubbing out
docs/source/narrative/index

Author: sigmavirus24

HISTORY.rst

@@ -1,13 +1,11 @@
 include README.rst
 include LICENSE
-include HISTORY.rst
-include LATEST_VERSION_NOTES.rst
 include AUTHORS.rst
 include CONTRIBUTING.rst
 include tox.ini
 include report_issue.py
 prune *.pyc
-recursive-include docs *.rst *.py Makefile
+recursive-include docs *.rst *.py
 recursive-include tests *.py *.json
 recursive-include tests/json *
 recursive-include tests/unit/json *

MANIFEST.in

@@ -1,6 +1,6 @@
-============
- github3.py
-============
+===================================================
+ github3.py: A Library for Using GitHub's REST API
+===================================================
 
 Release v\ |version|.
 
@@ -54,15 +54,24 @@ There are several examples of different aspects of using github3.py
 
 
 Installation
-------------
+============
 
 .. code-block:: console
 
     $ pip install github3.py
 
 
+User Guide
+==========
+
+.. toctree::
+    :maxdepth: 1
+
+    narrative/index
+
+
 API Reference Documentation
----------------------------
+===========================
 
 .. toctree::
     :maxdepth: 1
@@ -71,14 +80,14 @@ API Reference Documentation
 
 
 Contributing
-------------
+============
 
 All developlment happens on GitHub_. Please remember to add yourself to the
 list of contributors in AUTHORS.rst, especially if you're going to be
 working on the list below.
 
 Contributor Friendly Work
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 In order of importance:
 
@@ -96,7 +105,7 @@ Otherwise, feel free to example the list of issues where we would like help_
 and feel free to take one.
 
 Running the Unittests
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 The tests are generally run using tox. Tox can be installed lke so
 
@@ -142,26 +151,23 @@ more verbose output by doing
 
 
 Contact
--------
+=======
 
 - Twitter: `@sigmavirus24`_
 - Private email: graffatcolmingov [at] gmail
 
 .. _@sigmavirus24: https://twitter.com/sigmavirus24
 
-Latest Version's Changes
-------------------------
-
-.. include:: ../../LATEST_VERSION_NOTES.rst
-
-The full history of the project is available as well.
+Version History
+===============
 
 .. toctree::
+    :maxdepth: 1
 
-    project_changelog
+    release-notes/index
 
 Testimonials
-------------
+============
 
 .. raw:: html
 

docs/source/index.rst

@@ -0,0 +1,5 @@
+===========================
+ User Guide for github3.py
+===========================
+
+.. Add content

docs/source/narrative/index.rst

@@ -0,0 +1,39 @@
+0.1.0: 2012-11-13
+-----------------
+
+- Add API for GitHub Enterprise customers.
+
+0.1b2: 2012-11-10
+-----------------
+
+- Handle 500 errors better, courtesy of Kristian Glass (@doismellburning)
+
+- Handle sending json with ``%`` symbols better, courtesy of Kristian Glass
+
+- Correctly handle non-GitHub committers and authors courtesy of Paul Swartz 
+  (@paulswartz)
+
+- Correctly display method signatures in documentation courtesy of (@seveas)
+
+0.1b1: 2012-10-31
+-----------------
+
+- unit tests implemented using mock instead of hitting the GitHub API (#37)
+
+- removed ``list_*`` functions from GitHub object
+
+- Notifications API coverage
+
+0.1b0: 2012-10-06
+-----------------
+
+- Support for the complete GitHub API (accomplished)
+
+  - Now also includes the Statuses API
+
+  - Also covers the auto_init parameters to the Repository creation 
+    methodology
+
+  - Limited implementation of iterators in the place of list functions.
+
+- 98% coverage by unit tests

docs/source/project_changelog.rst

@@ -0,0 +1,23 @@
+0.2.0: 2012-11-21
+-----------------
+
+- MAJOR API CHANGES:
+
+  - ``GitHub.iter_subscribed`` --> ``GitHub.iter_subscriptions``
+
+  - Broken ``list_*`` functions in github3.api have been renamed to the correct
+    ``iter_*`` methods on ``GitHub``.
+
+  - Removed ``list_*`` functions from ``Repository``, ``Gist``,
+    ``Organization``, and ``User`` objects
+
+- Added zen of GitHub method.
+
+- More tests
+
+- Changed the way ``Repository.edit`` works courtesy of Kristian Glass
+  (@doismellburning)
+
+- Changed ``Repository.contents`` behaviour when acting on a 404.
+
+- 50% test coverage via mock tests

docs/source/release-notes/0.1.0.rst

@@ -0,0 +1,81 @@
+0.3.0: 2013-01-01
+-----------------
+
+- In github3.repos.Repository
+
+  - is_fork() and fork return the same thing
+
+  - is_private() and private return the same thing as well
+
+  - has_downloads, has_issues, has_wiki are now straight attributes
+
+- In github3.repos.Hook
+
+  - is_active() and active return the same value
+
+- In github3.pulls.PullRequest
+
+  - is_mergeable() and mergeable are now the same
+
+  - repository now returns a tuple of the login and name of the repository it 
+    belongs to
+
+- In github3.notifications.Thread
+
+  - is_unread() and unread are now the same
+
+- In github3.gists
+
+  - GistFile.filename and GistFile.name return the same information
+
+  - Gist.history now lists the history of the gist
+
+  - GistHistory is an object representing one commit or version of the history
+
+  - You can retrieve gists at a specific version with GistHistory.get_gist()
+
+- github3.orgs.Organization.iter_repos now accepts all types_
+
+- list_* methods on Organization objects that were missed are now deleted
+
+- Some objects now have ``__str__`` methods. You can now do things like:
+
+  .. code-block:: python
+
+    import github3
+    u = github3.user('sigmavirus24')
+    r = github3.repository(u, 'github3.py')
+
+  And
+
+  .. code-block:: python
+
+    import github3
+
+    r = github3.repository('sigmavirus24', 'github3.py')
+
+    template = """Some kind of template where you mention this repository 
+    {0}"""
+
+    print(template.format(r))
+    # Some kind of template where you mention this repository
+    # sigmavirus24/github3.py
+
+  Current list of objects with this feature:
+
+  - github3.users.User (uses the login name)
+
+  - github3.users.Key (uses the key text)
+
+  - github3.users.Repository (uses the login/name pair)
+
+  - github3.users.RepoTag (uses the tag name)
+
+  - github3.users.Contents (uses the decoded content)
+
+- 60% test coverage with mock
+
+- Upgrade to requests 1.0.x
+
+.. _types:
+    http://developer.github.com/v3/repos/#list-organization-repositories

docs/source/release-notes/0.2.0.rst

@@ -0,0 +1,33 @@
+0.4.0: 2013-01-16
+-----------------
+
+- In github3.legacy.LegacyRepo
+
+  - ``has_{downloads,issues,wiki}`` are now attributes.
+
+  - ``is_private()`` and the ``private`` attribute return the same thing 
+    ``is_private()`` will be deprecated in the next release.
+
+- In github3.repos.Repository
+
+  - ``is_fork()`` is now deprecated in favor of the ``fork`` attribute
+
+  - ``is_private()`` is now deprecated in favor of the ``private`` attribute
+
+- In github3.repos.Hook
+
+  - ``is_active()`` is now deprecated in favor of the ``active`` attribute
+
+- In github3.pulls.PullRequest
+
+  - ``is_mergeable()`` is now deprecated in favor of the ``mergeable`` 
+    attribute
+
+- In github3.notifications.Thread
+
+  - ``is_unread()`` is now deprecated in favor of the ``unread``
+
+- ``pubsubhubbub()`` is now present on the ``GitHub`` object and will be 
+  removed from the ``Repository`` object in the next release
+
+- 70% test coverage