Technical Documentation

Joshua E, Ryan M, Brett W, Mattie

To add more links to the table of contents, add a header anywhere on the doc and then hover over the box below and click the refresh.
Add Headings (Format > Paragraph styles) and they will appear in your table of contents.

Quick Commands

Virtual Env Setup

Manage project in VS Code

Git & GitHub setup

Creating a GitHub repo on the website

Add a .gitignore file to the new repo

Portfolio App Initialization

URI paths and routing

HTML Template

Version on the sprint01 branch

Adding static files

Version Tagging

Set up Database and Migrations

Create SuperUser and Login to Admin Panel

Create Student Model

Models and Relationships

NOTE: If you are using GitBash for Python commands on Windows, use py -3 instead of python3 as in the GE.

To activate a virtual environment (must be run from portfolio folder):

source  <venv name>/Scripts/activate

To start web server (must be run from within portfolio folder):

python manage.py runserver

# if that command doesn't work use this

py -3 manage.py runserver

NOTE: for all Python commands on Windows using GitBash, use py -3 instead of python3 as in the GE.

Open a command/terminal window (I used GitBash) and check your Python version. 

Python version command for Windows: 

# for Windows

py -3 --version

# for mac

python3 --version

Somewhere on your computer create a folder called cs3300 (I created mine in my cs3300-version-control Git repo from the first GE). Then make a portfolio folder for this GE. 

# run all these commands in order

mkdir cs3300

cd cs3300

mkdir portfolio

cd portfolio

Then create a virtual environment. If you want more information on Python virtual envs, check this article: Python Virtual Environments. After creating the venv (virtual environment), activate it. You need to be in the cs3300 directory to have this command work correctly. If you are in the djvenv folder, it will not work.

Note: On windows assuming you are not using bash or mingw you will not be able to use “source activate” and will need to instead run “./venv/activate.bat’

# create venv

py -3 -m venv djvenv

# activate it

source djvenv/Scripts/activate 

# NOTE: in GE, the command is "source djvenv/bin/activate" which does not work,  # you need to change the "bin" to "Scripts" like the command above

You should see something like this in the command line if you have activated the venv correctly:

Then install django in the venv with this command: Make sure to specify the version 4.2

# specify version 4.2 with django==4.2 

pip install django==4.2

Upgrade pip and create a django project

# upgrade pip

py -3 -m pip install --upgrade pip

# also run this to be safe

python.exe -m pip install --upgrade pip

# create django proj

django-admin startproject django_project

Reorder directory structure for ease of use

# you can do the same thing with these three commands

mv django_project/manage.py ./

mv django_project/django_project/* django_projectrm -r django_project/django_project/

(Basically move the manage.py file and django_project folder back one directory into the portfolio folder)

Portfolio folder should now look like this:

Run server and ignore migration warnings:

# run server

py -3 manage.py runserver

To verify the server was successful, go to http://localhost:8000/ or http://127.0.0.1:8000/ and you should see this:

Note: It may still say Django 5.0 on the top right even if you have version 4.2 installed. To verify django version:

django-admin --version

To stop the server, go back to your command/terminal and type CTRL+C. 

Open another terminal and activate the venv there

Once in the venv, create a requirements file of what is installed:

pip freeze > requirements.txt

Open VSCode (Or your IDE) and open the folder that contains the django project. In VS Code go to ‘File -> Open Folder’ and select the portfolio folder. 

To set the default terminal (powershell, command prompt, GIT bash etc), open the command palette (F1 or Ctrl+Shift+P) and type “Default Terminal”

Then select from the list which terminal you want as your default. 

NOTE: The GE document says to create a new private github repo to store the django project. However, I believe we all already have a private github repo from the first GE called cs3300-version-control so I just created the portfolio and subsequent django project in that existing repo. If this is not ok, I will update the documentation, but for now I did not have to re-create a new private repo for the django project. 

If you still want to create a new repo, here’s how:

Open the folder where your portfolio folder is, right click and select ‘Open Git Bash here’ or open your preferred terminal/command line interface. 

These commands will link the local repository to a remote GitHub repo

git init # initializes a repository in the current folder

echo "#CS3300 Private Repo" >> README.md # created a README file

git add . # adds all files to the staging area

git commit -m "Initial commit" 

git branch -M main # creates a main branch

git remote add main <URL of GitHub repo>

git push

You will need to go to GitHub.com and create a repository there to get the repository URL. 

Resources:

https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github

https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository

To get the URL of the GitHub repo, you need to create a repo on the website:

1. Go to GitHub.com and sign in. Click on Repositories and click on the New button.

2. Name the repo and make it private

3. Do not select add a README file and do not add a .gitignore or license. Just leave those options as they are.

4. Click “Create repository”

5. Find the SSH link under Quick Setup and use this command from earlier

git remote add main <URL of GitHub repo>

6. Then you can push your local repo

NOTE: You may have to set the upstream branch before you can push to the new repo

Use this article to add and format a .gitignore file

touch .gitignore

vi .gitignore

Once in the vi editor

1. press the “i” key to enter the Insert mode 

2. and paste (right click and select paste) the contents of this file in. 

3. Then find the # Environments section and add “/djvenv” or /”whatever you called your virtual environment”

4. Then press the “Esc” key, you should see the “Insert” at the bottom go away

5. and then the colon “:” key 

6. followed by “wq” and hit enter. 

7. That combination of keys will escape you from Insert mode, open the command window, and wq will “write” and then “quit” or save the file. After that, you should be back to the normal terminal screen. Check this article if a file is not being ignored.

Note: If you cannot get django-admin to run, you can either use docker, conda, or just
run “python -m django startapp portfolioSite” to bypass the need for the django cli.

In your portfolio_app folder, create a folder called templates, with a folder called portfolio_app inside of that.  Create the file base_template.html in the new portfolio_app folder, and paste the given code into it.  Also create an index.html file in this directory, and paste the code given for this page in as well.

The file in \templates\portfolio_app\base_template.html contains links for pages called Logout and Login.  It is advisable to add the above lines to make the page work.  Without them, the page will produce errors and not load properly.

Assuming you’ve created a sprint01 branch already, you can do the following from a command line to commit and push your changes to this branch.  First, navigate to the root directory of the local repository.  Run the following:

GE03 Documentation

Technical Documentation Joshua E, Ryan M, Brett W, Mattie

To add more links to the table of contents, add a header anywhere on the doc and then hover over the box below and click the refresh. Add Headings (Format > Paragraph styles) and they will appear in your table of contents.

Quick Commands Virtual Env Setup Manage project in VS Code Git & GitHub setup Creating a GitHub repo on the website Add a .gitignore file to the new repo Portfolio App Initialization URI paths and routing HTML Template Version on the sprint01 branch Adding static files Version Tagging Set up Database and Migrations Create SuperUser and Login to Admin Panel Create Student Model Models and Relationships Quick Commands NOTE: If you are using GitBash for Python commands on Windows, use py -3 instead of python3 as in the GE. To activate a virtual environment (must be run from portfolio folder): source /Scripts/activate To start web server (must be run from within portfolio folder): python manage.py runserver

py -3 manage.py runserver Virtual Env Setup NOTE: for all Python commands on Windows using GitBash, use py -3 instead of python3 as in the GE. Open a command/terminal window (I used GitBash) and check your Python version. Python version command for Windows:

py -3 --version

python3 --version

Somewhere on your computer create a folder called cs3300 (I created mine in my cs3300-version-control Git repo from the first GE). Then make a portfolio folder for this GE.

mkdir cs3300 cd cs3300 mkdir portfolio cd portfolio

Then create a virtual environment. If you want more information on Python virtual envs, check this article: Python Virtual Environments. After creating the venv (virtual environment), activate it. You need to be in the cs3300 directory to have this command work correctly. If you are in the djvenv folder, it will not work.

Note: On windows assuming you are not using bash or mingw you will not be able to use “source activate” and will need to instead run “./venv/activate.bat’

py -3 -m venv djvenv

source djvenv/Scripts/activate

You should see something like this in the command line if you have activated the venv correctly:

Then install django in the venv with this command: Make sure to specify the version 4.2

pip install django==4.2

Upgrade pip and create a django project

py -3 -m pip install --upgrade pip

python.exe -m pip install --upgrade pip

django-admin startproject django_project

Reorder directory structure for ease of use

mv django_project/manage.py ./ mv django_project/django_project/* django_projectrm -r django_project/django_project/

(Basically move the manage.py file and django_project folder back one directory into the portfolio folder)

Portfolio folder should now look like this:

Run server and ignore migration warnings:

py -3 manage.py runserver

To verify the server was successful, go to http://localhost:8000/ or http://127.0.0.1:8000/ and you should see this:

Note: It may still say Django 5.0 on the top right even if you have version 4.2 installed. To verify django version: django-admin --version

To stop the server, go back to your command/terminal and type CTRL+C.

Open another terminal and activate the venv there

Once in the venv, create a requirements file of what is installed: pip freeze > requirements.txt Manage project in VS Code Open VSCode (Or your IDE) and open the folder that contains the django project. In VS Code go to ‘File -> Open Folder’ and select the portfolio folder.

To set the default terminal (powershell, command prompt, GIT bash etc), open the command palette (F1 or Ctrl+Shift+P) and type “Default Terminal”

Then select from the list which terminal you want as your default.

Git & GitHub setup NOTE: The GE document says to create a new private github repo to store the django project. However, I believe we all already have a private github repo from the first GE called cs3300-version-control so I just created the portfolio and subsequent django project in that existing repo. If this is not ok, I will update the documentation, but for now I did not have to re-create a new private repo for the django project.

If you still want to create a new repo, here’s how: Open the folder where your portfolio folder is, right click and select ‘Open Git Bash here’ or open your preferred terminal/command line interface.

These commands will link the local repository to a remote GitHub repo git init # initializes a repository in the current folder echo "#CS3300 Private Repo" >> README.md # created a README file git add . # adds all files to the staging area git commit -m "Initial commit" git branch -M main # creates a main branch git remote add main git push You will need to go to GitHub.com and create a repository there to get the repository URL. Creating a GitHub repo on the website Resources: https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository To get the URL of the GitHub repo, you need to create a repo on the website: Go to GitHub.com and sign in. Click on Repositories and click on the New button. Name the repo and make it private Do not select add a README file and do not add a .gitignore or license. Just leave those options as they are. Click “Create repository” Find the SSH link under Quick Setup and use this command from earlier git remote add main Then you can push your local repo NOTE: You may have to set the upstream branch before you can push to the new repo

Add a .gitignore file to the new repo Use this article to add and format a .gitignore file touch .gitignore vi .gitignore Once in the vi editor press the “i” key to enter the Insert mode and paste (right click and select paste) the contents of this file in. Then find the # Environments section and add “/djvenv” or /”whatever you called your virtual environment”

Then press the “Esc” key, you should see the “Insert” at the bottom go away and then the colon “:” key followed by “wq” and hit enter.

That combination of keys will escape you from Insert mode, open the command window, and wq will “write” and then “quit” or save the file. After that, you should be back to the normal terminal screen. Check this article if a file is not being ignored. Portfolio App Initialization Note: If you cannot get django-admin to run, you can either use docker, conda, or just run “python -m django startapp portfolioSite” to bypass the need for the django cli. URI paths and routing

HTML Template In your portfolio_app folder, create a folder called templates, with a folder called portfolio_app inside of that. Create the file base_template.html in the new portfolio_app folder, and paste the given code into it. Also create an index.html file in this directory, and paste the code given for this page in as well.

The file in \templates\portfolio_app\base_template.html contains links for pages called Logout and Login. It is advisable to add the above lines to make the page work. Without them, the page will produce errors and not load properly.

Version on the sprint01 branch Assuming you’ve created a sprint01 branch already, you can do the following from a command line to commit and push your changes to this branch. First, navigate to the root directory of the local repository. Run the following: git checkout 'sprint01' git add . git commit -m 'commit message' git push -set-upstream origin sprint01

Adding static files Create the directory where the static files will be stored, make sure it is in the base directory of “portfolio”. The directory should look like this after you complete this section, except you’ll have a single image, either .gif or .png work.

Update settings.py so Django can find the static files settings.py location: \portfolio\django_project\settings.py

Add line 12 to settings.py

Ensure settings.py has lines 122-128 as such.

Update base_template.html base_template.html location: \portfolio\portfolio_app\templates\portfolio_app\base_template.html

Add line 1 to the HTML file.

Update line 16 to what is shown.

Open up http://127.0.0.1:8000/ and check that the Navbar displays the image.

Version Tagging For the purpose of this activity, you can tag the current branch with: git tag GE02

However, to get the tag to show up in the remote repository, it is crucial that you use: git push origin --tag

GE03 Documentation Set up Database and Migrations

Create SuperUser and Login to Admin Panel

Create Student Model

Models and Relationships