Please write better examples for documentation

[davidawad]

there's no way to know how to use this if you've never used the github API before.

[pelegm]

I wouldn't say it is true, and in any case, you are more than welcome to contribute.

As a quick start, try:

>>> g = github.Github(token)
>>> u = g.get_user()
>>> print u.name
David Awad
>>> print u.hireable
True
>>> print u.followers
94
>>> r = sorted(u.get_repos(), key=lambda r: r.stargazers_count, reverse=True)[0]
>>> print "The repository {r.name} has {r.stargazers_count} stars!".format(r=r)
The repository SpaceShare has 32 stars!

etc.

[thefourtheye]

Totally agree. If I have to quickly create a program, then this module is totally of no use. I have to go through the classes and understand how to use them.

[pconrad]

So, I put a lot of time into writing a collection of such examples and putting them on the "wiki" associated with the repo. But I don't see a way to access that "wiki" anymore, and I'm wondering if github.com dropped the "wiki" associated with each repo while I wasn't paying attention?

[pconrad]

Here are some: https://github.com/UCSB-CS-Using-GitHub-In-Courses/PyGitHubExamples

[thefourtheye]

@pconrad Oh thanks :-) But I ended up using github3.py

[bronger]

http://pygithub.github.io/PyGithub/ is also of interest. Is it linked from somewhere here? I think the links in https://github.com/PyGithub/PyGithub/blob/master/doc/introduction.rst should be updated.

[a35joshi]

https://media.readthedocs.org/pdf/pygithub/stable/pygithub.pdf
Good document but requires some effort to comprehend.

[p00j4]

is there any good usage doc on dealing with Pull Requests?
this is more of a dev doc
I want to use it for easy parsing for a any pull request- event received from github webhook in which I get is the payload json, which @ the moment, I'm parsing on my own. i'm keen to look at usage examples to analyze if this using PyGithub, the tedious parsing efforts are gonna actually be reduced.

[sks444]

Hello everyone,
I have started writing examples for PyGithub, have a look and feel free to contribute ;)

[sfdye]

Latest docs on readthedocs site should be easy to follow now.

[MaslowCommunityGardenRobot]

I still think that more and better documentation is needed, especially examples. The documentation is easy to read and well done, but having never worked with the github API before it is not clear how to actually implement the functions. What is a blob...how to I create one...etc

[sfdye]

@MaslowCommunityGardenRobot I agree. I am thinking of starting a new PyGithub by examples section on the docs, but we would require a lot of user contributions for it. Is this something that would interest you?

[BarbourSmith]

I would gladly contribute if it was easy to make pull requests to. After working with pygithub for a couple weeks now it's really easy to use and well written, but a couple clear examples would have helped me a lot getting started and I am happy to contribute them as long as you give them a look over to make sure I'm doing things right 😉

[sfdye]

@BarbourSmith That sounds brilliant! I can't wait to see you PR. Maybe start with a simple doc/example-usage.rst? Once the page looks good I will try to merge it to readthedocs itself 😃

[allardbrain]

@sfdye I'd like to jump in here and start the Examples section. Like others have said above, PyGithub is a great resource but took me some time to figure out how to manipulate the Classes and methods for my use. Any preference for how to structure the Examples section? I'm thinking a simple Class-by-Class approach might be good, to mirror the reference documentation itself.

[BarbourSmith]

This is still on my todo list too. Life keeps getting in the way, but I would love to help @allardbrain

[allardbrain]

@BarbourSmith Great! Let's each pick a few examples we'd like to start with so we don't overlap. Since my current personal project involves using the ContentFile class, I'll start there. Here's a link to my forked version which now has doc/example-usage.rst and some boilerplate.

[BarbourSmith]

Great! It's going to be at least another week or two before I will really have time to dig in, but I'm mostly dealing with reading issues and comments and merging pull requests so it sounds like we'll have good coverage

[sfdye]

Thank you @allardbrain @BarbourSmith for bringing up this topic.

How about we start a examples folder under docs, and document each class with one rst? i.e. examples/issue.rst, examples/pullrequest.rst. Please share your PR once it's ready 😉 so we have a place to discuss.

[allardbrain]

@sfdye Sounds good to me. Excited to work on this!

@BarbourSmith no problem.

[BarbourSmith]

I'm running into an issue while documenting the PullRequest class which is that a lot of the features that users will want when interacting with pull requests are ONLY available by using the issue class.

To read the comments on a pull request you need to open it as an issue instead of a pull request and access the comments that way. The PullRequest class has a comments attribute, but it is not the comments you see when opening the pull request on the GitHub website which is what you would expect.

Similarly to close a pull request you need to open it as an issue and use prAsIssue.edit(state='closed') .

Because a good example often includes multiple classes I think we might be better off with a single examples.rst file instead of separate files for each class.

How do we feel about having a single examples.rst file?

[sfdye]

@BarbourSmith Wouldn’t hurt, let’s start with that :)

[BarbourSmith]

I opened #762 to start us off

[BarbourSmith]

@allardbrain Have you had a chance to work on this any more? I'm looking for info on using the using the ContentFile class, even just one simple example would help me a lot.

This blog post also includes more examples which are useful:

https://chase-seibert.github.io/blog/2016/07/22/pygithub-examples.html

[allardbrain]

@BarbourSmith I am still trying to figure out how to use parts of this package for a project I have due on Friday. I can start writing examples once I submit it. This should help in the mean time:

from github import Github
import os

GITHUB_API_KEY = os.environ['GITHUB_API_KEY']
g = Github(GITHUB_API_KEY)

def get_code():
    user = g.get_user('scipy')
    repo = user.get_repo('scipy')
    self.code = repo.get_contents('setup.py').decoded_content

    return

[BarbourSmith]

That helps a ton. Thank you.

[vipulgupta2048]

Anyone who is working on PyGithub examples will earn a free Issue fixed in your repo. We need more examples desperately. @BarbourSmith I am looking at your examples, they help so much. Thanks for being an angel.

[p00j4]

I'm adding my examples in this Pull Reuest, would like to know, where to add them, as examples/pullrequest.rst structure is still not in this repository.
Can we have a branch out where the skelenton is started and all contributors work from that branch and when its looks in shape, we can again raise to the master @vipulgupta2048 @sfdye ?

[sfdye]

@p00j4 Commented on #762 and let's use that thread to discuss.

[sfdye]

Please see #874