installing via `pip install -e path/to/mhkit`

[ssolson]

We need to change the documentation to remove references to python setup.py develop. It is recommended to pip install these files in editable mode. pip install -e path/to/MHKiT

Then to switch between MHKiT documentation and a develop version one would

pip uninstall mhkit
pip install -e path/to/otherMHKiT

Originally posted by @ssolson in https://github.com/MHKiT-Software/MHKiT/pull/15#issuecomment-627328455

[kmruehl]

The documentation does not currently tell the user to specify the mhkit path. It says, pip install -e. and needs to be updated. Here is the console output:

pip install -e

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> ...

-e option requires 1 argument

[ssolson]

Kelly the documentation does not say "pip install -e." it says "pip install -e ." where the period is the argument. It means here. The line above this one has already directed the user into the mhkit-Python folder.

[kmruehl]

@ssolson I was not familiar with the pip install -e . syntax and actually thought the period was a typo. I recommend modifying the installation guidance to more more explicit, like you stated earlier in this feed: pip install -e path/to/MHKiT.

Also, it would be useful to specify a documentation syntax for referencing the local path to the MHKiT source code, for example: $MHKiT, path/to/MHKiT or <mhkit_path>.

[ssolson]

Kelly what about adding a note that the "." means here?

I originally implemented this documentation with what you suggest doing e.g.: "path/to/MHKiT" However, Rebecca suggested removing the path in favor of the period. I agree with this implementation because copy and paste now provide the correct result.

With respect to having a text variable e.g. $MHKiT Sean found this very confusing when he first encountered it at some other point in the documentation. I think his interpretation provides a pretty good feel for general documentation users and I am not in favor of implementing this.

[kmruehl]

@ssolson i think the c/p comment is a valid one, and perhaps a note would help people like me who are unfamiliar with the . syntax. However, perhaps this is common knowledge and a note isn't necessary.

That's useful feedback, and it sounds like the $MHKiT syntax is not a good one to use. But since we do refer to the MHKiT path several times throughout the documentation, it would be good to specify a standard syntax, for example: path/to/MHKiT or <mhkit_path>, etc.