Add a how-to on running the project

Question

Add a how-to on running the project

tracey-le opened this issue 8 years ago · 22 comments

The how-to will be for anyone to look at, like from other groups, or for example I'll look at it if I've forgotten how to do it at any point in future :)

Answer 1 · 2017-01-21T23:02:16.000Z

Are there conventions for this sort of thing? For example, is it usually done in the README.md, or is there another place where you could put it?

Answer 2 · 2017-01-21T23:08:51.000Z

I'll just quickly note down things for the how-to.

Outline for how to run

this is quickly for in GitHub Desktop
Clone repo (Screenshot) only if first time
Open Terminal/Git Shell (Screenshot again)
basic command is python file.py to run a file named file.py
only if first time running, need to create the db. python db/db_create.py (Screenshot with note that python3 is for Mac for example)
each time you want to run the project you need the server, run python server.py (Screenshot)
open a browser, type in localhost:8888
(insert pic of site)
and can view in Atom by going to Repository>Open in Atom (Insert screenshot with note this is Mac version)

Answer 3 · 2017-01-21T23:17:05.000Z

Yes, this is normally done in the README.md. Here's an example (and a shameless self-promotion 😛).

Answer 4 · 2017-01-21T23:28:35.000Z

I'm gonna do a little draft here and put screenshots ^_^ this will be meant for totally starting at the start, like if I've forgotten everything or am doing it on another device

-this is free to edit at any point. I'm editing it too

How to run — Draft

This is quickly for GitHub Desktop.

After setting up GitHub desktop, click the + button in the top left corner. Log into GitHub account if you haven't already.
After clicking the + button, from options of [Add | Create | Clone], choose Clone to clone the repository only if first time

(If the group project 3 doesn't show here as an option for cloning, you would have to go to GitHub projects 2017 group 3 link I think??)
Once the project has finished cloning, it will appear in the left panel under GitHub. Open in Terminal/Git Shell by right-clicking on project name:

(The name of the option 'Open in Terminal/Git Shell' is just dependent on whichever Operating System you are using. I am using a Mac here.)

In shell, if you want to run a Python file named file.py for example, you can type in python db_create.pyonce you're in the directory of the file.

Only if first time running, we need to create the database (this also contains the dummy data). python db/db_create.py is the command to run the file that creates the database (on at least Windows I think).
Here is a screenshot (this is for Mac where python3 is for running python3)
Now, each time you want to run the project, you need the server. Run python server.py

If it worked and the server's working, you'll see the Reloading... waiting for requests on http://localhost:8888 message appear.
After you have the server, open a browser and type in localhost:8888 to see our awesome site

Messages will keep appearing in the shell as you do things on the site, this is expected.

And you can view code in Atom by going to Repository>Open in Atom on Mac, I think there's a button on Windows with the Atom icon.
Screenshot for Mac:

or you can also right-click on the project name and then Open in Atom:

If you have any ideas or comments on this tutorial, please feel very free to add.

Answer 5 · 2017-01-21T23:29:30.000Z

@lyneca 👍

Answer 6 · 2017-01-21T23:29:48.000Z

I've done some stuff in pull request #15

Answer 7 · 2017-01-21T23:39:40.000Z

That's awesome 👍 we just need to create the database the first time running the project though — for the dummy data I think, so I think we can just mention python db_create.py is for the first time, and each time afterwards you just need python server.py

Answer 8 · 2017-01-21T23:45:21.000Z

just curious, I've heard of bash but not sure what it does, what does it do? 😊

Answer 9 · 2017-01-22T00:14:21.000Z

bash is a linux shell - like a language for terminals

Answer 10 · 2017-01-22T00:18:01.000Z

oh okay, thank you 😊 I'm not quite sure still but it's okay 👍

Answer 11 · 2017-01-22T00:33:11.000Z

Okay I think I'm done with the how-to draft for now ☺️ I can just put it as a more in-depth/newbie-friendly version somewhere, don't know where though. I don't know how the images will load if I put it in a file?

edit: I don't think the images will work in a file, maybe I could put it somewhere here on GitHub.

what is Wiki usually used for? It looks more for documenting and managing project but happy to put it there if that's okay

Answer 12 · 2017-01-22T00:52:58.000Z

Images can be put in a readme.

![Alt text](http://full/path/to/img.jpg "Optional title")

Put the images on imgur or something and put the full image URL in that bit of code, such as this:

![picture of a cat](https://i.imgur.com/F60i2Ga.jpg "Cat Photo")

Get the full image path by right clicking on the image and hitting "copy image address".

EDIT

You can just copy the image and paste it into GitHub's editor as well 😛

Answer 13 · 2017-01-22T00:56:35.000Z

Wikis are used for making user-created documentation for a project. Probably not what we're looking for in this case.

Answer 14 · 2017-01-22T01:21:47.000Z

Oooh okay thank you for the how-to on images in Markdown 😄 oh okay, I see for wikis now, yep probably not for this.

hmm I was thinking about either updating README.md with that extra info, or I could add it to /documentation? I don't know

Answer 15 · 2017-01-22T01:40:22.000Z

I think put it in README.md; it's the document that shows up when you first look at the project.

Answer 16 · 2017-01-22T01:43:59.000Z

cool thanks Luke :D

Answer 17 · 2017-01-22T03:03:54.000Z

Once this is merged here #17, I'll close this issue 😃 (but always feel free to edit and add things to the how-to)

Answer 18 · 2017-01-22T03:11:57.000Z

— as I mentioned in last commit description

The images are a bit big and some of the spacing is off

so always free to edit :) the main things are there so I'm just gonna leave it for now

Answer 19 · 2017-01-22T03:26:11.000Z

just updating the how-to with another image instead, uploading it here so I can use the link hehe..

Answer 20 · 2017-01-23T11:04:41.000Z

Now it's merged into master thanks to @juliawong 😄

Answer 21 · 2017-01-24T01:43:06.000Z

basic how-to is there so I closed this

ideas for improvement (can re-open issue or make another one):

upload smaller images and re-link the image links in README.md (or experiment and see if html <img> elements work?)
fix some of the spacing (try <br>?)

Answer 22 · 2017-01-26T23:47:21.000Z

yay I've done those little changes now, with the resized images and the spacing :) :D