Tutorial and documentation examples in general missing large amount of context

[catskul]

The tutorial pulls code out from the middle of a test case which is great in that it should stay up to date, but bad in that it's missing a huge amount of context.

It starts out using object properties that are created off stage, and are extremely hard to find even when one goes digging:

"The first step is to create a git.Repo object to represent your repository.

    from git import Repo
    join = os.path.join

    # rorepo is a a Repo instance pointing to the git-python repository.
    # For all you know, the first argument to Repo is a path to the repository
    # you want to work with
    repo = Repo(self.rorepo.working_tree_dir)
    assert not repo.bare

"

As you can see, apart from trivial missing imports for os, reference to self.rorepo is without context, creating rorepo would be a logical step before this in such a tutorial.

[Byron]

self.rorepo is created automatically, showing that is not possible and wouldn't contribute to the tutorial. The comment tries to say that the first argument is the path to the repository, and works with that from thereon.
Would it help if I'd link the original source file for people to see more of the surroundings ?
How would you alleviate the issue, assuming that self.rorepo is somewhat off the charts - it's a Repo pointing to GitPythons own repository.
Thanks for the feedback.

[catskul]

Thanks for the reply, and the maintenance and development work on GitPython!

This is just my opinion, but I think the easiest thing to do would be to just replace some of those blocks with explicit code rather than referencing the tests which by nature are going to be much more complicated.

In this example I'd just change it to

from git import Repo
path = './path/to/non_empty/repo'
repo = Repo( path )

IMO the idea of pulling from the tests for examples seems to be a better idea in theory than in practice. In the case that the API changes, even if the example code gets updated to reflect it, the surrounding text could very easily then be out of date.

[Byron]

You're welcome !

There was a time when the examples were not tested, and people would have issues with example code not actually working. I'd rather have code that is definitely reflecting the actual API with regression tests than having to maintain that manually (which wouldn't happen anyway).

This leaves only one option: Annotate the code more to make clear how to read and understand it. Considering I already link the underlying test-suite on github, I am not sure what else to do.

Maybe I am just 'blind' for this matter. Considering you had to figure out how to work with the tests, you might be able to add some documentation to help others figure it out as well.

PRs are, as usual, very welcome.

If this conclusion is sufficient for you, please close this issue. Otherwise feel free to sketch a path of action to improve the docs.
Thanks

[catskul]

If I get some free time, I'll make a PR. Closing for now.

[brettswift]

FYI: thanks for this conversation. It helped out a new guy to python who was confused to what the cryptic name osp was.