search

Freeseer / freeseer

Designed for capturing presentations at conferences. Pre-fill a list of talks to record, record them, and upload them to YouTube with our YouTube Uploader.
http://freeseer.readthedocs.org
GNU General Public License v3.0
215 stars 110 forks source link

Related to #432: Add instructions to Contribute docs on how to install requirements #591

Closed benbuckley closed 9 years ago

benbuckley commented 9 years ago

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.

dideler commented 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?

dideler commented 9 years ago

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.

benbuckley commented 9 years ago

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"?

zxiiro commented 9 years ago

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.

benbuckley commented 9 years ago

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?

dideler commented 9 years ago

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.

dideler commented 9 years ago

Closing since 1b114d527b896a75d0509c5c58cf064c91e9c2b5 and 19da061516cf05e1cd364163be4b67529602ad9b improve the installation steps.