Tutorial: first example code is very unclear and confusing

[pbb72]

trafficstars

The first example code in the tutorial is very unclear:

from git import Repo

# rorepo is 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

To start with, this just gives me the error message

NameError: name 'self' is not defined

The comment "rorepo is a Repo instance pointing to the git-python repository" doesn't help. Does this mean "rorepo" is just an example word, and I have to replace it with something from my own system? Does this reference a directory or a repository name I should create on my filesystem? The term "rorepo" doesn't come up any other places in the whole documentation.

Also the following text is only adding to the confusion. "In the above example, the directory self.rorepo.working_tree_dir equals /Users/mtrier/Development/git-python ..." NOT IT DOESN'T. Maybe it does on the specific system for the documentation writer, but it is not a general rule.

The use of "For all you know..." is very ironic here; this expression literally means that the "you" (the reader) doesn't know what the writer wants...

Please modify the tutorial code to apply to general users. if code requires previous actions/setup, then please specify this.

[Handballfreak]

Same issues here. In generall the documentation is more confussing than it helps.

[Byron]

There can only be agreement on this, as the tutorial section prefers correctness and testability over being easy to follow. Most certainly the intend of it should be made clearer to set expectations.

Since you have been bitten by this and certainly an opinion, I would be happy to see a PR with adjustment that you would have wanted the first time around. It probably won't take much to at least set expectations, without needing to modify the way it's done as this would be way more work that I don't expect anyone to do really.

Thanks for your consideration.

[pbb72]

Hi Byron, thank you for your reaction. However, I do not think you understand my situation as a reader.

I read the tutorial, and get confused by it. Obviously, this means I do not understand much about GitPython. That is the reason I am reading the tutorial. And yet you suggest I send you a PR with how the tutorial should have been written.

How do you think I can do this? I am not capable of writing a tutorial for GitPython! If I was, I wouldn't need one... All I can do, is report that it is not understandable for someone who needs a tutorial.

Sometimes expecting people who report problems, also to give you the solution, goes a bit too far!

[Byron]

So maybe this is the solution: Change the headline from something including the word 'Tutorial' to something that makes clear what it is: A tour through the major bits of the API using a test suite. If it's consumed under this pretence, I would hope it's easier to grasp.

When asking for a contribution, I was trying to ask for any adjustment that makes it easier to understand what it is that you are looking at. "… without needing to modify the way it's done as this would be way more work that I don't expect anyone to do really." tries to make clear that this should not be major alteration of the 'tutorial', but some added context to prepare people for what's to expect.

Since you explicitly point out a passage that can be perceived as ironic, fixing that one seems like a simple way to leave this place better than you found it.

[tacerus]

How do I get a repo instance from the working directory? There is no rorepo to be found and self is not defined without any wrapper code. The documentation should in my opinion not be a one to one copy from the test suite if it's not possible to use it as a standalone reference.

[Byron]

Indeed, it's not possible to copy-paste most of it, but from what I can tell it explains itself and the peculiarities coming with being runnable in the test-suite.

I do appreciate the attempt to improve it but believe it's preferable to stay consistent. If improvements should be made, I think this should be done in the form of adjusting variable names in the underlying test, or by improving the comments.