Improve documentation

Contributing.rst

@@ -0,0 +1,37 @@
+Contributing
+============
+
+Issues
+------
+
+A good issue includes a `short, self contained, correct example <http://sscce.org/>`_ of the problem, something like::
+
+    assert github.Github().get_user("jacquev6").name == "Vincent Jacques"
+
+It is even better if you provide the debug logs associated with your issue.
+Enable them with :func:`github.enable_console_debug_logging` and copy them in the body of the issue.
+Warning, you may want to remove some private information (authentication information is removed, but there may be private stuff in the messages)
+
+If for any reason you are not able to do that, open your issue anyway and we will see what is needed to solve your problem.
+
+Pull requests
+-------------
+
+Please do your pull requests on the ``develop`` branch.
+
+Automated tests
+~~~~~~~~~~~~~~~
+
+You can run the tests through ``python -m github.tests``. Run a specific test with ``python -m github.tests TestCase`` or ``python -m github.tests TestCase.testMethod``.
+
+If you add a new test, for example ``Issue139.testCompletion``, you must add an import in ``github/tests/AllTests.py``. Then, you have to run ``python -m github.tests Issue139.testCompletion --record`` to create the ``github/tests/ReplayData/*.txt`` files needed for you new test. Check them and commit them as well. You will need a ``GithubCredentials.py`` file at the root of the project with the following contents::
+
+	login = "my_login"
+	password = "my_password"
+	oauth_token = "my_token"  # Can be left empty if not used
+
+Coding conventions
+~~~~~~~~~~~~~~~~~~
+
+PyGithub follows `pep8 Style Guide for Python Code <http://www.python.org/dev/peps/pep-0008/>`_ except for line length.
+Please check your code with `pep8 Python style guide checker <http://pypi.python.org/pypi/pep8>`_, by running ``pep8 --ignore=E501 github``.

ReadMe.rst

@@ -1,5 +1,4 @@
 This is a Python (2 and 3) library to access the `Github API v3 <http://developer.github.com/v3>`_.
-
 With it, you can manage your `Github <http://github.com>`_ resources (repositories, user profiles, organizations, etc.) from Python scripts.
 
 It covers the **full** API, and all methods are tested against the real Github site.
@@ -11,53 +10,15 @@ PyGithub is stable. I will maintain it up to date with the API, and fix bugs if
 What's new?
 ===========
 
-`![Build Status](https://secure.travis-ci.org/jacquev6/PyGithub.png)] <http://travis-ci.org/jacquev6/PyGithub>`_
-
-Next version
-------------
-
-* Much better documentation http://jacquev6.github.com/PyGithub.
+`![Build Status](https://travis-ci.org/jacquev6/PyGithub.png?branch=master)] <http://travis-ci.org/jacquev6/PyGithub>`_
 
-Previous versions
------------------
+`Version 1.12.0 <https://github.com/jacquev6/PyGithub/issues?milestone=22&state=closed>`_ (February 17th, 2013)
+---------------------------------------------------------------------------------------------------------------
 
-See `ChangeLog <https://github.com/jacquev6/PyGithub/blob/master/doc/ChangeLog.md>`_.
+* Much better documentation: http://jacquev6.github.com/PyGithub
+* `Implement <https://github.com/jacquev6/PyGithub/issues/140>`_ :meth:`github.Repository.Repository.get_gir_contents`. Thank you `ksookocheff-va <https://github.com/ksookocheff-va>`_ for asking
 
-Dcumentation
-============
+Documentation
+=============
 
 All the documentation is here: http://jacquev6.github.com/PyGithub.
-
-Licensing
-=========
-
-PyGithub is distributed under the GNU Lesser General Public Licence.
-See files COPYING and COPYING.LESSER, as requested by `GNU <http://www.gnu.org/licenses/gpl-howto.html>`_.
-
-Contributing
-============
-
-Please see `Contributing.md <https://github.com/jacquev6/PyGithub/blob/master/doc/Contributing.md>`_.
-
-Projects using PyGithub
-=======================
-
-(`Open an issue <https://github.com/jacquev6/PyGithub/issues>`_ if you want to be listed here, I'll be glad to add your project)
-
-* `Upverter <https://upverter.com>`_ is a web-based schematic capture and PCB layout tool for people who design electronics. Designers can attach a Github project to an Upverter project.
-* `Notifico <http://n.tkte.ch>`_ receives messages (such as commits and issues) from services and scripts and delivers them to IRC channels. It can import/sync from Github.
-* `Tratihubis <http://pypi.python.org/pypi/tratihubis/>`_ converts Trac tickets to Github issues
-* https://github.com/CMB/cligh
-* https://github.com/natduca/quickopen uses PyGithub to automaticaly create issues
-* https://gist.github.com/3433798
-* https://github.com/zsiciarz/aquila-dsp.org
-* https://github.com/robcowie/virtualenvwrapper.github
-
-They talk about PyGithub
-========================
-
-* http://stackoverflow.com/questions/10625190/most-suitable-python-library-for-github-api-v3
-* http://stackoverflow.com/questions/12379637/django-social-auth-github-authentication
-* http://www.freebsd.org/cgi/cvsweb.cgi/ports/devel/py-pygithub/
-* http://oddshocks.com/blog/2012/08/02/developing-charsheet/
-* https://bugzilla.redhat.com/show_bug.cgi?id=910565

doc/.gitignore

@@ -1,2 +1,3 @@
 /build/
 github_objects.rst
+contributing.rst

doc/apis.rst

@@ -3,7 +3,7 @@ APIs
 
 * ``/authorizations``
 
-  * GET: :func:`github.AuthenticatedUser.AuthenticatedUser.get_authorizations`
+  * GET: :meth:`github.AuthenticatedUser.AuthenticatedUser.get_authorizations`
   * POST: :meth:`github.AuthenticatedUser.AuthenticatedUser.create_authorization`
 
 * ``/authorizations/:id``

doc/changes.rst

@@ -13,23 +13,23 @@ Stable versions
 --------------------------------------------------------------------------------------------------------------
 
 * Fix bug in PaginatedList without url parameters. Thank you `llimllib <https://github.com/llimllib>`_ for the `contribution <https://github.com/jacquev6/PyGithub/pull/133>`_
-* `Implement <https://github.com/jacquev6/PyGithub/issues/130>`_ `NamedUser.get_keys`
-* `Support PubSubHub <https://github.com/jacquev6/PyGithub/issues/129>`_: `Repository.subscribe_to_hub` and `Repository.unsubscribe_from_hub`
-* `Publish the oauth scopes <https://github.com/jacquev6/PyGithub/issues/134>`_ in Github.oauth_scopes, thank you `bilderbuchi <https://github.com/bilderbuchi>`_ for asking
+* `Implement <https://github.com/jacquev6/PyGithub/issues/130>`_ :meth:`github.NamedUser.NamedUser.get_keys`
+* `Support PubSubHub <https://github.com/jacquev6/PyGithub/issues/129>`_: :meth:`github.Repository.Repository.subscribe_to_hub` and :meth:`github.Repository.Repository.unsubscribe_from_hub`
+* `Publish the oauth scopes <https://github.com/jacquev6/PyGithub/issues/134>`_ in :attr:`github.Github.Github.oauth_scopes`, thank you `bilderbuchi <https://github.com/bilderbuchi>`_ for asking
 
 `Version 1.10.0 <https://github.com/jacquev6/PyGithub/issues?milestone=16&state=closed>`_ (December 25th, 2012) (Christmas 2012 edition)
 ----------------------------------------------------------------------------------------------------------------------------------------
 
 * Major improvement: support Python 3! PyGithub is automaticaly tested on `Travis <http://travis-ci.org/jacquev6/PyGithub>`_ with versions 2.5, 2.6, 2.7, 3.1 and 3.2 of Python
-* Add a shortcut function 'Github.get_repo' to get a repo directly from its full name. thank you `lwc <https://github.com/lwc>`_ for the contribution
-* 'Github.get_gitignore_templates' and 'Github.get_gitignore_template' for APIs '/gitignore/templates'
-* Add the optional 'ref' parameter to 'Repository.get_contents' and 'get_readme'. Thank you `fixxxeruk <https://github.com/fixxxeruk>`_ for the contribution
-* Get comments for all issues and all pull requests on a repository ('GET /repos/:user/:repo/pulls/comments': 'Repository.get_pulls_comments' or 'Repository.get_pulls_review_comments'; 'GET /repos/:user/:repo/issues/comments': 'Repository.get_issues_comments')
+* Add a shortcut function :meth:`github.Github.Github.get_repo` to get a repo directly from its full name. thank you `lwc <https://github.com/lwc>`_ for the contribution
+* :meth:`github.Github.Github.get_gitignore_templates` and :meth:`github.Github.Github.get_gitignore_template` for APIs ``/gitignore/templates``
+* Add the optional ``ref`` parameter to :meth:`github.Repository.Repository.get_contents` and :meth:`github.Repository.Repository.get_readme`. Thank you `fixxxeruk <https://github.com/fixxxeruk>`_ for the contribution
+* Get comments for all issues and all pull requests on a repository (``GET /repos/:user/:repo/pulls/comments``: :meth:`github.Repository.Repository.get_pulls_comments` or :meth:`github.Repository.Repository.get_pulls_review_comments`; ``GET /repos/:user/:repo/issues/comments``: :meth:`github.Repository.Repository.get_issues_comments`)
 
 `Version 1.9.1 <https://github.com/jacquev6/PyGithub/issues?milestone-17&state-closed>`_ (November 20th, 2012)
 --------------------------------------------------------------------------------------------------------------
 
-* Fix an assertion failure when integers returned by Github do not fit in a Python `int`
+* Fix an assertion failure when integers returned by Github do not fit in a Python ``int``
 
 `Version 1.9.0 <https://github.com/jacquev6/PyGithub/issues?milestone-14&state-closed>`_ (November 19th, 2012)
 --------------------------------------------------------------------------------------------------------------

doc/conf.py

@@ -11,7 +11,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys, os, shutil
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -259,3 +259,5 @@
 			github_object.write("=" * len(obj) + "\n")
 			github_object.write("\n")
 			github_object.write(".. autoclass:: github." + obj + "." + obj + "()\n")
+
+shutil.copyfile("../Contributing.rst", "contributing.rst")

doc/index.rst

@@ -7,3 +7,4 @@ PyGithub
    introduction
    reference
    changes
+   contributing

doc/introduction.rst

@@ -15,13 +15,13 @@ First create a Github instance::
 
     from github import Github
 
-    g = Github( "user", "password" )
+    g = Github("user", "password")
 
 Then play with your Github objects::
 
     for repo in g.get_user().get_repos():
         print repo.name
-        repo.edit( has_wiki = False )
+        repo.edit(has_wiki=False)
 
 Download and install
 --------------------
@@ -42,3 +42,26 @@ What next?
 You need to use a Github API and wonder which class implements it? `Reference of APIs <todo internal link>`_
 
 You want all the details about PyGithub classes? `Reference of classes <todo internal link>`_
+
+Projects using PyGithub
+-----------------------
+
+(`Open an issue <https://github.com/jacquev6/PyGithub/issues>`_ if you want to be listed here, I'll be glad to add your project)
+
+* `Upverter <https://upverter.com>`_ is a web-based schematic capture and PCB layout tool for people who design electronics. Designers can attach a Github project to an Upverter project.
+* `Notifico <http://n.tkte.ch>`_ receives messages (such as commits and issues) from services and scripts and delivers them to IRC channels. It can import/sync from Github.
+* `Tratihubis <http://pypi.python.org/pypi/tratihubis/>`_ converts Trac tickets to Github issues
+* https://github.com/CMB/cligh
+* https://github.com/natduca/quickopen uses PyGithub to automaticaly create issues
+* https://gist.github.com/3433798
+* https://github.com/zsiciarz/aquila-dsp.org
+* https://github.com/robcowie/virtualenvwrapper.github
+
+They talk about PyGithub
+------------------------
+
+* http://stackoverflow.com/questions/10625190/most-suitable-python-library-for-github-api-v3
+* http://stackoverflow.com/questions/12379637/django-social-auth-github-authentication
+* http://www.freebsd.org/cgi/cvsweb.cgi/ports/devel/py-pygithub/
+* http://oddshocks.com/blog/2012/08/02/developing-charsheet/
+* https://bugzilla.redhat.com/show_bug.cgi?id=910565

github/Github.py

@@ -34,7 +34,7 @@
 
 class Github(object):
     """
-    This class represents Githubs as returned for example by http://developer.github.com/v3/todo
+    This is the main class you instanciate to access the Github API v3. Optional parameters allow different authentication methods.
     """
 
     def __init__(self, login_or_token=None, password=None, base_url=DEFAULT_BASE_URL, timeout=DEFAULT_TIMEOUT, client_id=None, client_secret=None, user_agent=None):

github/InputFileContent.py

@@ -16,7 +16,6 @@
 
 class InputFileContent(object):
     """
-    This class represents InputFileContents as returned for example by http://developer.github.com/v3/todo
     """
 
     def __init__(self, content):

github/InputGitAuthor.py

@@ -16,7 +16,6 @@
 
 class InputGitAuthor(object):
     """
-    This class represents InputGitAuthors as returned for example by http://developer.github.com/v3/todo
     """
 
     def __init__(self, name, email, date):

github/InputGitTreeElement.py

@@ -18,7 +18,6 @@
 
 class InputGitTreeElement(object):
     """
-    This class represents InputGitTreeElements as returned for example by http://developer.github.com/v3/todo
     """
 
     def __init__(self, path, mode, type, content=github.GithubObject.NotSet, sha=github.GithubObject.NotSet):

github/PaginatedList.py

@@ -70,19 +70,19 @@ def __finished(self, index):
 
 class PaginatedList(PaginatedListBase):
     """
-    This class abstracts the `pagination of the API <http://developer.github.com/v3/todo>`_.
+    This class abstracts the `pagination of the API <http://developer.github.com/v3/#pagination>`_.
 
-    You can simply enumerate through instances of this class:
+    You can simply enumerate through instances of this class::
 
         for repo in user.get_repos():
             print repo.name
 
-    You can also index them or take slices:
+    You can also index them or take slices::
 
         second_repo = user.get_repos()[1]
         first_repos = user.get_repos()[:10]
 
-    And if you really need it, you can explicitely access a specific page:
+    And if you really need it, you can explicitely access a specific page::
 
         some_repos = user.get_repos().get_page(0)
         some_other_repos = user.get_repos().get_page(3)

setup.py

@@ -17,7 +17,7 @@
 import setuptools
 import textwrap
 
-version = "1.11.1",
+version = "1.11.1"
 
 if __name__ == "__main__":
     setuptools.setup(
@@ -26,26 +26,26 @@
         description="Use the full Github API v3",
         author="Vincent Jacques",
         author_email="vincent@vincent-jacques.net",
-        url="http://vincent-jacques.net/PyGithub",
+        url="http://jacquev6.github.com/PyGithub",
         long_description=textwrap.dedent("""\
-            Tutorial
-            ========
+            (Very short) Tutorial
+            =====================
 
-            First create a Gihub instance::
+            First create a Github instance::
 
                 from github import Github
 
-                g = Github( "user", "password" )
+                g = Github("user", "password")
 
             Then play with your Github objects::
 
                 for repo in g.get_user().get_repos():
                     print repo.name
-                    repo.edit( has_wiki = False )
+                    repo.edit(has_wiki=False)
 
             You can also create a Github instance with an OAuth token::
 
-                g = Github( token )
+                g = Github(token)
 
             Or without authentication::
 
@@ -54,7 +54,7 @@
             Reference documentation
             =======================
 
-            See http://vincent-jacques.net/PyGithub"""),
+            See http://jacquev6.github.com/PyGithub"""),
         packages=[
             "github",
             "github.tests",