Closed ssolson closed 4 years ago
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
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.
@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>
.
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.
@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.
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
Originally posted by @ssolson in https://github.com/MHKiT-Software/MHKiT/pull/15#issuecomment-627328455