Editable install instructions on contributing page could be clearer

[andypbarrett]

It looks like there is a typo on the contributing page.

I think

pip install -e.

should be

pip install -e .

[JessicaS11]

Thanks, @andypbarrett! I can't remember where or when I learned it (and of course am not finding it documented anywhere), but the two are equivalent. I use pip install -e. all the time (yay for not having to type that extra character!). Have you encountered use cases where that doesn't work? If so, we should definitely update the docs. Otherwise, do you think it's worth a note that either works?

[weiji14]

I tried to add a space in https://github.com/icesat2py/icepyx/pull/187/commits/2ec4e6fca7f0ebc8896e07fc4182e64114181537, but Jessica said the same thing in https://github.com/icesat2py/icepyx/pull/187#issuecomment-804061697 and reverted it back :laughing:

[andypbarrett]

Mmmm I just tried it again and pip install -e. worked. Weird! I thought spaces mattered in linux.

I suggest closing the issue because it is a red hering.

[andypbarrett]

Alternatively add that pip install -e. and pip install -e . both work. Now I want to understand why they both work.

[JessicaS11]

Alternatively add that pip install -e. and pip install -e . both work.

probably a good idea given it seems to be a recurring theme... 😆

Now I want to understand why they both work.

Curious to know if you figure it out. I think I learned it in a youtube video of a "how to make Python software" workshop that Lindsey Heagey recommended for me when we started icepyx. It was one of those narrative "you can do this without the space instead and it works" things. 🤷‍♀️

[mfisher87]

This is a confusing aspect of POSIX shortform argument behavior. Often, for example, one wants to quickly specify shortform arguments and their values:

du -hd1

This passes the --human-readable flag and the --depth option with the value 1 to du. It's short, but it's not readable. There are additional problems. Order matters. What about du -d1h?

$ du -d1h
du: invalid maximum depth ‘1h’
Try 'du --help' for more information.

Only one specific way of glomming the arguments into a single incantation gives us the :magic_wand: magic :tophat: :rabbit2: we're looking for! However, du --depth 1 --human-readable is clear and can be broken down and re-written in different order.

IMO, for educational content, we should strictly avoid short-form arguments and go for --editable instead of -e to avoid any confusion. There is no option to omit the space after the long-form argument:

$ pip install --editable.

Usage:   
  pip install [options] <requirement specifier> [package-index-options] ...
  pip install [options] -r <requirements file> [package-index-options] ...
  pip install [options] [-e] <vcs project url> ...
  pip install [options] [-e] <local project path> ...
  pip install [options] <archive url/path> ...

no such option: --editable.

[mfisher87]

https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html

An option and its argument may or may not appear as separate tokens. (In other words, the whitespace separating them is optional.) Thus, -o foo and -ofoo are equivalent.