Permalink
Browse files

Improve documentation

  • Loading branch information...
1 parent 680490a commit 0bd00452e78cd39cd3b07c076f7bb56fb8a75e3e @jacquev6 jacquev6 committed Feb 16, 2013
View
@@ -1,31 +0,0 @@
-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 `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.
-
-PyGithub follows [pep8 Style Guide for Python Code](http://www.python.org/dev/peps/pep-0008/) except for line length.
-So if you do heavy modifications, please check your code with [pep8 Python style guide checker](http://pypi.python.org/pypi/pep8), by running `pep8 --ignore=E501 github`.
-
-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
View
@@ -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``.
View
@@ -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
View
@@ -1,2 +1,3 @@
/build/
github_objects.rst
+contributing.rst
View
@@ -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``
View
@@ -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)
--------------------------------------------------------------------------------------------------------------
View
@@ -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")
View
@@ -7,3 +7,4 @@ PyGithub
introduction
reference
changes
+ contributing
View
@@ -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
View
@@ -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):
@@ -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):
@@ -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):
@@ -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):
@@ -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)
View
@@ -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",

0 comments on commit 0bd0045

Please sign in to comment.