Closed benbuckley closed 9 years ago
There are some instructions on this subject in the Quick Start guide (http://freeseer.readthedocs.org/en/latest/quick-start.html) but they seem to be aimed at people installing Freeseer, rather than running it from the source.
Those instructions are under a section called "Installing Freeseer for Development" which I thought would be clear enough. But maybe it's not?
This change isn't related to the Git/GitHub setup, so I don't think it's the right place to put it.
If you think it's really needed, I suggest adding a note or seealso that points to quick-start.html#pypi-packages.
@wigglier already made a label for that section (yet to be merged), see the label here and an example of a reference here.
This change isn't related to the Git/GitHub setup, so I don't think it's the right place to put it.
Fair enough -- I do think that it needs to be made more obvious somewhere, though.
As it is in the Quick Start guide, under the heading "Installing Freeseer for Development", the subheadings are "Dependencies", "Debian and Ubuntu Linux", "Fedora Linux", "Windows", "PyPi Packages", and "Get the Source Code" -- a sufficiently lazy reader (i.e. me) might be seduced into thinking "I only need to read the instructions for Ubuntu -- the rest of the subheadings don't apply to me."
This might be a good opportunity for me to clarify for myself on a deeper level what it means to "install" something in Linux. When I was getting ready to start using Freeseer, I basically just tried to do what the Quick Start guide and the Basics page for contributors told me to do, but I suppose I didn't completely understand it. If I want to play with the Freeseer code, is it necessary to install Freeseer as described in the QuickStart guide -- what would happen if I had just downloaded the source code, installed the PyPi packages, gone to freeseer/src, and typed in "python -m freeseer"?
We recommend that you install if you intend to use Freeseer as an end-user. If you are instead developing Freeseer or want to tweak the code then you should download the source version instead and run it as you mentioned.
It is important to ensure that if you are using the source version to have Freeseer UNINSTALLED, otherwise Python will be confused about which Freeseer files it will run.
As I look more closely at the Quick Start guide, the instructions under "Installing Freeseer for Development" appear to be instructions on installing all the necessary packages, then at the end, even after instructing the reader to use Pip to install the requirements listed in requirements.txt and dev_requirements.txt, finally explains that you need to fork and clone the project. Perhaps this should be at the top of the "Installing Freeseer for Development" section, rather than at the end?
a sufficiently lazy reader (i.e. me) might be seduced into thinking "I only need to read the instructions for Ubuntu -- the rest of the subheadings don't apply to me."
This is valuable feedback - it seems like this is the real issue. We'll need to think about this some more to see what we can do to make it better. That said, I don't think the proposed changes in this PR is the right solution since it's more like trying to rescue from the error than preventing it. What we could possibly do, is add a seealso below every OS section to the PyPI section. I'm open to more ideas.
what would happen if I had just downloaded the source code, installed the PyPi packages, gone to freeseer/src, and typed in "python -m freeseer"?
If you do this, without having installed Freeseer via some package manager first, then Freeseer should launch.
Perhaps [PyPI section and source code section] should be at the top of the "Installing Freeseer for Development" section, rather than at the end?
This is probably a better suggestion than mine above. I think this could work.
Closing since 1b114d527b896a75d0509c5c58cf064c91e9c2b5 and 19da061516cf05e1cd364163be4b67529602ad9b improve the installation steps.
I added an instruction on how to install the requirements listed in requirements.txt and dev_requirements.txt. This seemed like a good idea, because it wasn't obvious to me at the beginning. There are some instructions on this subject in the Quick Start guide (http://freeseer.readthedocs.org/en/latest/quick-start.html) but they seem to be aimed at people installing Freeseer, rather than running it from the source. #432 seemed like the most relevant pre-existing issue to match this change.
EDIT: As I look at the commits, they seem to include some artifacts of my early experiments with Git, wherein I made changes directly to the master, frantically tried to undo my mistakes by making more mistakes, and didn't understand the difference between "merge" and "rebase" -- not totally sure how to change those at this point.