README.md improve wording, formatting

[keikoro]

I changed the variable used in the README from os to ost (see #16), and then also went and improved wording/spelling and (code) formatting of the rest of the file along with it:

• replaced interpreter/console code with regularly formatted Python code (like it'd be used in a file)
• changed formatting for code blocks to use triple backticks with python keyword (for syntax-highlighting on GitHub)
• improved Markdown structure (headlines/hierarchical structure)

[agonzalezro]

I like the changes you did, but I am not sure the changes to the code blocks will still work with pydoctests, could you try it?

Also, you will need to add documentation about the download you implemented (in the PR where you are implementing it).

[agonzalezro]

I am not sure this will work with pydoctest. Did you try it?

[keikoro]

I didn't test anything because there aren't any tests included - to me, the testing instructions in the README read as incomplete example (as if they were started but never finished).

So, am I interpreting this correctly that everyone is supposed to test "manually" (with the code provided) instead of using a ready-made file/class? Wouldn't it make more sense to include that in the repo and then only have people set values for variables? (For their local file names.)

[keikoro]

Ohhh, wait. Having never used pydoctest, I thought the bit about testing was wrt a "regular" testing framework, when actually it's specifically for code examples in documentation? Huh, the more you know!

I'll have to read up on this.

[keikoro]

Hmm, ok, based on quickly skimming info on this, it looks like it won't work if it doesn't find >>> to denote examples for interactive Python sessions...

I never use the interpreter for anything but the simplest tests, definitely not for playing around with libraries, so find code examples given like that very impractical (bad for copy-pasting bits and pieces and harder to read due to formatting). But I don't know if this is maybe an unusual usage pattern.

[agonzalezro]

Those pydoctests will not work either because I am almost 100% sure that you don't have the film Dark City downloaded in: "Dark.City.1998.Directors.Cut.BRRip.H264.AAC.5.1ch.Gopo.mp4" :) That's why I mentioned on #18 that the tests should be moved and probably moved out from the README.

pydoctests is nice when you don't need a lot of setup for the tests, at the moment you need mocks I think it kinda miss its point.

[keikoro]

Yup, saw #18. Not sure what to do with this PR for now. Should the changes wait until other tests are implemented?

[agonzalezro]

@kerstin maybe do the changes you proposed but without touching the code snippets (you can change os for ost though). What do you think?

[keikoro]

Will revert the changes to the code snippets.

[keikoro]

(Personally, I would make/keep them regular code style than interpreter-style though because as said, it makes copy/pasting examples easier, regardless of where one wants to use the code. They'd need some adapting to be even more useful and more readable – which I think they currently aren't all, which has to do with the superfluous punctuation –, like removal of the assert statements, which are indicative that this is all about testing (written for a computer)... whereas I think a README should be about explaining things (written for humans).)

[agonzalezro]

hi @kerstin I agree that having documentation that is easy to copy/paste is a good idea; however, since we don't have proper tests yet don't change the formatting of the code here. We can do it after adding the tests somewhere else.

[keikoro]

Yeah, I didn't include the instructions for the download part yet because I was waiting for feedback on the overall changes to the README first.

I find it easier to work with separate independent changes/commits than to have to go back and untangle one big commit of which only parts are accepted!

[agonzalezro]

@kerstin I agree with not adding the download help in this PR, but it should be on the other one.

[keikoro]

Updated!

[agonzalezro]

Thanks again for your help @kerstin!