1. Gestion de projet et documentation#

Getting started with gitlab#

First thing first we had to create our gitlab acount and link our student repository to our personal computer. This is done through the command line interface (CLI).

SSH key#

The connection between your computer and gitlab is done thanks to an SSH key. You can create one yourself through the CLI.

ssh-keygen 

I then copied the public key and added it in the “SSH keys” setting on gitlab.

Git clone and pull#

With the ssh key in place, safe connection between gitlab and my computer is possible. I installed git on my computer.
To clone I had to copy the link of the repository (Code button on gitlab account) and then use the following command in the gitlab folder of my computer

git clone <copied-url>

To download the latest changes on the project, use

git pull

Add, commit and push#

With everything in place I can now work on my gitlab project directly from my computer. Nevertheless the changes aren’t directly loaded on the gitlab account. To do so, use

git add <change>
git commit -m "comment on change"
git push 

The first command adds/confirms the change. The second commits the it on the main branch and the third is to upload the changes on the gitlab account. It is also possible to do do copies of your project (branches) and work on them without risking any change on the main one. To create a branch, go in your project’s file and use

git checkout -b <name-of-branch>

“git checkout” alone allows to navigate through your different branches.

Using markdown for documentation#

Documenting and sharing what we learn, try, and fail is an important part of this class. For this task, we will essentialy be using Markdown, a lightweight markup language for creating formatted text.

Here is a quick markdown memo

Tips:

• Put a double space at the end of a sentence for a line break

  After this sentence i would like a line break
  Hooray for double spaces

• Don’t try putting images next to text without using css. The output isn’t often good.

Mkdocs#

Mkdocs is a static site generator. The mkdocs package must first be installed on your computer. You can create a new project with:

mkdocs new projct-name

To start the server and view your site, go in your project folder (more imortantly in the same directory as the mkdocs.yml file) and run mkdocs serve.

Create a new page to your doc with,

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/page_name.md

Add your pages in the nav section of your mkdocs.yml file.

site_name: MkLorum
nav:
  - Home: index.md
  - New Page: page_name.md

The last step is to build your documentation.

mkdocs build

Images#

In order to have a better controle over my images, I added markdown extensions to my mkdocs.yml file that unlock new options on them.

markdown_extensions: 
  - attr_list       // align your image left or right
  - md_in_html      // markdown options such as width :O 

Adding new options is now simple and elegant:

![Image Title](source){ align=right width=200}

Licences#

When starting a project accessible to others, it is important to specify what people can or cannot do with your work. Creative commons (CC) licences where created to answer this question.

A CC-license uses the following

• BY: credit must be given to the creator
• SA: Adaptations must be shared under the same terms
• NC: Only noncommercial uses of the work are permitted
• ND: No derivatives or adaptations of the work are permitted

A CC-license allways has the BY option. More details about CC-licenses here.