README.md, Documentations, and Examples All Out of Date

[dayfine]

I was trying to switch over from rules_python_external. At first I made a naive change following the current README.md, which didn't work (code compiles but then modules are not imported in runtime). Then I read the instructions again, tried pip3_import, which doesn't exist (under pip.bzl). I then actually read pip.bzl, and tried to do what the comment says, which doesn't work (the code expects requirements.txt under an external directory, i.e. the comment is misleading). Lastly I followed the example and appended // to the requirement file, which felt odd and unnecessary (and realized this was what I was doing with rules_python_external.

Also the repo is not versioned often enough, many of the instruction seems to be for 0.1.0 while the code have moved past it. I ended up simply using HEAD / master.

For the record, the change that I ended up making: a54bf79 (#50)

[thundergolfer]

Thanks for the feedback, and sorry that you've had trouble with the switch. I have some questions to try and get at some specific things we could change in the docs.

Then I read the instructions again, tried pip3_import ...

Oh yep, I see this in the README and it is unhelpful that pip3_import isn't in pip.bzl but in the legacy file. I can fix this.

the code expects requirements.txt under an external directory, i.e. the comment is misleading

What do you mean by this? AFAIK the requirements file just needs to be in any directory in the workspace that is a package (ie. has a BUILD file in it). If you could link to a specific line containing the misleading comment that would be helpful.

and appended // to the requirement file, which felt odd and unnecessary

Should be unnecessary, but sounds plausible that ":requirements.txt", gets interpreted as relative to the rules_python external repo instead of relative to the user's (internal) workspace, which is unambiguous when the argument is "//:requirements.txt", like you have.

Also the repo is not versioned often enough, many of the instruction seems to be for 0.1.0 while the code have moved past it.

This is always going to be the case. The README is concerned with the latest release which is 0.1.0. Are you saying just saying that we should do another release now because of recent changes landing on master?

[dayfine]

This is always going to be the case. The README is concerned with the latest release which is 0.1.0. Are you saying just saying that we should do another release now because of recent changes landing on master?

My thought process was like this:

1. README says use pip3_import (or do anything else) and install version X, say 0.1.0
2. Doesn't work at version X
3. Me thinking: does pip3_import work with 0.1.0, i.e. is doc outdated?
4. Me then thinking: I am too lazy to find the commit for 0.1.0 since it has been a while ago. Let me find out if pip3_import works at HEAD
5. Found out pip3_import doesn't work at HEAD
6. Found out something else work at HEAD
7. Puzzled that README.md still refers to (what is supposed to work at) v0.1.0, when what works at HEAD is not officially documented

[thundergolfer]

@dayfine Can you suggest further actions items to address this issue, so we can make progress towards closing it? Already we've picked out and merged one fix (#398).

[thundergolfer]

After #495 was merged concerns about pip3_import documentation should be addressed. Please let me know if other issues need fixing 🙏