From 0bd00452e78cd39cd3b07c076f7bb56fb8a75e3e Mon Sep 17 00:00:00 2001 From: Vincent Jacques Date: Sat, 16 Feb 2013 21:15:17 +0100 Subject: [PATCH] Improve documentation --- Contributing.md | 31 -------------------- Contributing.rst | 37 ++++++++++++++++++++++++ ReadMe.rst | 53 +++++------------------------------ doc/.gitignore | 1 + doc/apis.rst | 2 +- doc/changes.rst | 16 +++++------ doc/conf.py | 4 ++- doc/index.rst | 1 + doc/introduction.rst | 27 ++++++++++++++++-- github/Github.py | 2 +- github/InputFileContent.py | 1 - github/InputGitAuthor.py | 1 - github/InputGitTreeElement.py | 1 - github/PaginatedList.py | 8 +++--- setup.py | 18 ++++++------ 15 files changed, 97 insertions(+), 106 deletions(-) delete mode 100644 Contributing.md create mode 100644 Contributing.rst diff --git a/Contributing.md b/Contributing.md deleted file mode 100644 index ac15d2be..00000000 --- a/Contributing.md +++ /dev/null @@ -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 diff --git a/Contributing.rst b/Contributing.rst new file mode 100644 index 00000000..22defbd7 --- /dev/null +++ b/Contributing.rst @@ -0,0 +1,37 @@ +Contributing +============ + +Issues +------ + +A good issue includes a `short, self contained, correct example `_ 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 `_ except for line length. +Please check your code with `pep8 Python style guide checker `_, by running ``pep8 --ignore=E501 github``. diff --git a/ReadMe.rst b/ReadMe.rst index 3a7f61ae..8440604e 100644 --- a/ReadMe.rst +++ b/ReadMe.rst @@ -1,5 +1,4 @@ This is a Python (2 and 3) library to access the `Github API v3 `_. - With it, you can manage your `Github `_ 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)] `_ +`![Build Status](https://travis-ci.org/jacquev6/PyGithub.png?branch=master)] `_ -Next version ------------- +`Version 1.12.0 `_ (February 17th, 2013) +--------------------------------------------------------------------------------------------------------------- -* Much better documentation http://jacquev6.github.com/PyGithub. +* Much better documentation: http://jacquev6.github.com/PyGithub +* `Implement `_ :meth:`github.Repository.Repository.get_gir_contents`. Thank you `ksookocheff-va `_ for asking -Previous versions ------------------ - -See `ChangeLog `_. - -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 `_. - -Contributing -============ - -Please see `Contributing.md `_. - -Projects using PyGithub -======================= - -(`Open an issue `_ if you want to be listed here, I'll be glad to add your project) - -* `Upverter `_ 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 `_ receives messages (such as commits and issues) from services and scripts and delivers them to IRC channels. It can import/sync from Github. -* `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 diff --git a/doc/.gitignore b/doc/.gitignore index 28bed887..90adc9f2 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,2 +1,3 @@ /build/ github_objects.rst +contributing.rst diff --git a/doc/apis.rst b/doc/apis.rst index 0ea07627..bff00fa2 100644 --- a/doc/apis.rst +++ b/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`` diff --git a/doc/changes.rst b/doc/changes.rst index e8c073fd..9b87d912 100644 --- a/doc/changes.rst +++ b/doc/changes.rst @@ -13,23 +13,23 @@ Stable versions -------------------------------------------------------------------------------------------------------------- * Fix bug in PaginatedList without url parameters. Thank you `llimllib `_ for the `contribution `_ -* `Implement `_ `NamedUser.get_keys` -* `Support PubSubHub `_: `Repository.subscribe_to_hub` and `Repository.unsubscribe_from_hub` -* `Publish the oauth scopes `_ in Github.oauth_scopes, thank you `bilderbuchi `_ for asking +* `Implement `_ :meth:`github.NamedUser.NamedUser.get_keys` +* `Support PubSubHub `_: :meth:`github.Repository.Repository.subscribe_to_hub` and :meth:`github.Repository.Repository.unsubscribe_from_hub` +* `Publish the oauth scopes `_ in :attr:`github.Github.Github.oauth_scopes`, thank you `bilderbuchi `_ for asking `Version 1.10.0 `_ (December 25th, 2012) (Christmas 2012 edition) ---------------------------------------------------------------------------------------------------------------------------------------- * Major improvement: support Python 3! PyGithub is automaticaly tested on `Travis `_ 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 `_ 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 `_ 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 `_ 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 `_ 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 `_ (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 `_ (November 19th, 2012) -------------------------------------------------------------------------------------------------------------- diff --git a/doc/conf.py b/doc/conf.py index bf1e0ee0..9e311aa9 100644 --- a/doc/conf.py +++ b/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 @@ with open("github_objects.rst", "w") as github_objects: github_object.write("=" * len(obj) + "\n") github_object.write("\n") github_object.write(".. autoclass:: github." + obj + "." + obj + "()\n") + +shutil.copyfile("../Contributing.rst", "contributing.rst") diff --git a/doc/index.rst b/doc/index.rst index 42fcde3a..5c16e2c2 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -7,3 +7,4 @@ PyGithub introduction reference changes + contributing diff --git a/doc/introduction.rst b/doc/introduction.rst index 6a225b1d..a2d40a6f 100644 --- a/doc/introduction.rst +++ b/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 `_ You want all the details about PyGithub classes? `Reference of classes `_ + +Projects using PyGithub +----------------------- + +(`Open an issue `_ if you want to be listed here, I'll be glad to add your project) + +* `Upverter `_ 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 `_ receives messages (such as commits and issues) from services and scripts and delivers them to IRC channels. It can import/sync from Github. +* `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 diff --git a/github/Github.py b/github/Github.py index 10dbfb01..3715f34d 100644 --- a/github/Github.py +++ b/github/Github.py @@ -34,7 +34,7 @@ DEFAULT_TIMEOUT = 10 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): diff --git a/github/InputFileContent.py b/github/InputFileContent.py index 88aade39..cc3fd59b 100644 --- a/github/InputFileContent.py +++ b/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): diff --git a/github/InputGitAuthor.py b/github/InputGitAuthor.py index dbf6b390..d501d1c1 100644 --- a/github/InputGitAuthor.py +++ b/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): diff --git a/github/InputGitTreeElement.py b/github/InputGitTreeElement.py index 4b211e23..7a4c57ec 100644 --- a/github/InputGitTreeElement.py +++ b/github/InputGitTreeElement.py @@ -18,7 +18,6 @@ import github.GithubObject 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): diff --git a/github/PaginatedList.py b/github/PaginatedList.py index 10e7f380..dfc696ad 100644 --- a/github/PaginatedList.py +++ b/github/PaginatedList.py @@ -70,19 +70,19 @@ class PaginatedListBase: class PaginatedList(PaginatedListBase): """ - This class abstracts the `pagination of the API `_. + This class abstracts the `pagination of the API `_. - 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) diff --git a/setup.py b/setup.py index fe76396e..2d1a8501 100755 --- a/setup.py +++ b/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 @@ if __name__ == "__main__": 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 @@ if __name__ == "__main__": Reference documentation ======================= - See http://vincent-jacques.net/PyGithub"""), + See http://jacquev6.github.com/PyGithub"""), packages=[ "github", "github.tests",