2. Project management¶
with version control and web¶
Aim¶
In This week I learned the process of the documentation of my projects and the related tools. Moreover, the possibility to cooperate with my other classmates and tutors in the following projects. Firs I need to setup a webpage where I can document my weekly progress. There are many tools these days for generating static webpages. I will try to use as many tool in order to understand capability of them.
Also, Git as tool for version control has been presented and all the process of web developing will be in track with it. I know about git before but never tried it in any project. I think this is a good chance to rehearse this tool.
Web development¶
I always wants to make my personal website but hearing the names of many languages that is used for it made me scared. So this week was a great chance for me to overcome my fears and start to make it.
In the following I will describe my experience with different tools and the result of my exploration.
Useful links¶
Static and dynamic web generators¶
As I understood in order to make a webpage there are many different methods other then HTML/CSS/JS.
So the html can be generate with a software, which is called Static site generators such as mcdocs and jekyll. Alternatively, It can be made on the server on the fly.
In other word, when you send the http request to a specific domain, the server will send back an html to our browser. When the website is static it means the server just send the static html that we provide to it. However, when the page is dynamic the server will first run a code to generate the html file from certain instruction that is provide for it.
I start first with the static site generators(ssg). Then, I went further to make to try dynamic one as well. For the static site, I start with the mcdocs and jekyll. I tried with plain HTML as well to understant better the functionality of the template making of those two.
After this I moved to wagtail and Django to make the website dynamically.¶
mkdocs¶
I guess mkdocs was the simplest one among the other tools for web generating. But for me it was a bit hard at first to grasp the folder structure. But after I dived into it, became very familiar and convenient. The good thing about this is that does not take a lot of time to set it up and it is quit fast forward structure. This feature allowed me to be more productive in the content rather than the web developing.
Setup¶
firs you should now this software is base on the python so inorder to use this generator you need to install python on your system. I had Python 3.7 on my machine before but as reference you can Download it in the following link.
while you installing make sure that you check the –Add the Python to the environment PATH– so you can access it with the command line.
Then you need to install the pip. you can use the following command in the terminal to do it.
python get-pip.py
After I installed mkdocs library with
pip install mkdocs
in the next step I cloned the repository of our simple website and start modifying it.
editing¶
So in each mkdocs project there is a mkdocs.yml file which contain some meta data and variable for mkdocs compiler. for instance the name of the webpage, the them and colors. I edit the name and them. In addition, I changed the meta data for the social media.
limitation¶
mcdocs was really fast pace platform and easy to follow, but it has some down side. The most problematic one is the styling. Even though that I tried to overwrite so features for my home page it did not worked well. Also I wanted to add a slid-bar to home page to shows the latest updates of my assignment which was almost impossible to add.
HTML¶
After working with mkdocs and understood its limitation. I thought it would be nice to start making an html pure html file. I just opened my text editor(atom or sublime) and start writing HTML.
I have used bootstrap4 for CSS to make my work easer. Nevertheless, I realized that the amount of the lines that I have to copy and past is so much.
Setup¶
editing¶
For editing, I was going from different template and layout to the others and take somethings. This made my website very chaotic
limitation¶
// the setup function runs once when you press reset or power the board
jekyll¶
Setup¶
Requirements¶
editing¶
limitation¶
// the setup function runs once when you press reset or power the board
wagtail/Django¶
Django is a framework for developing web applications and wagtail is a content management platform based on Django. In contrast with the other techniques that I mentioned, this tools used to make a dynamic webpage.
Setup¶
Since Django is based on python you have to have it on your system. you can follow the installation steps in mkdocs section. after that you need to install the Django and wagtail by
pip install Django
pip install
before installing this I made the virtual environment for my website project to eliminate any confliction with my other python packages.
Requirements¶
-python -text editor
limitation¶
// the setup function runs once when you press reset or power the board
Git¶
Setup¶
Download the Git from their website for windows 64bit architecture. the last available version is 2.25.0
Tip: While installing make sure that your adding the git PATH to your system environment. so you can access it git command from windows command line.
Requirements¶
-Git installation on the machine
-Public SSH key
-Online Repository
My interpretation¶
I used to use git before even though it was a long time that have not implemented it in my projects. This week was good wake up call to remind me about the importance of this tool for project management. Now that I start using it again for my webpage, it is feel so natural and I am already comfortable with it.
So the command that I am mostly using are:¶
git help
git commit -m "description of change"
git commit -a -m "description of change"
The important note is to always write a good short description for each commit so it can give me a hint about the main change. The -a in the second command is adding the new files while committing to others, which is a compressed version of
git add . filename
git commit -m "description"
To check the repository changes and the commits
git status
git log
After I finish a set of development I push it to the online depository by
git push
Now I want to start a new feature for front-end of my page but I am not sure how it will go. So I will make a branch to not change the master that is working currently. The command that is gonna do that is
git branch
whenever I have got sure about the changes I can simply merge the branch to the master, which means all the changes that I applied in the branch will be updated into main project. I can do that by
git merge
Facing the problems:¶
so during this week while I was working on my project, I start adding photos to my images folder and committing locally. Eventually, after a while when I wanted to push my commits to my repository, it did not allow me to do so due to the commit size limitation.
So I had to first use
git repack
to merge some unnecessary commits. Then I tried to force it to push by
git push origin master
but it did not work. I found out that I can push the commits step by step to the master with
git push remote "the commit id":master
so in this case I gradually update my master to reach to the same point as my local repository.
The other problem that I faced was losing the SHH key to my repository. I generate another key for my github account. However, I did not know that it will lose the other key. So I just needed to copy the new one and add a new SSH key to my Gitlab account. I used the following command to copy the existed key.
$ clip < ~/.ssh/id_rsa.pub