Skip to content

Windows (Graphical install)

First of all I need to mention that I’m working on a Windows machine… Which sometimes can be very frustrating…

The project template supplyed by fabacademy is based on mkdocs. Mkdocs is basically the website generator, it is based on python which is both a programming language and a software translating code to computer operation in realtime (It’s called an interpreted language)

It is possible to deal with package using terminal on windows using a piece of sofware named chocolatey. Chocolatey is a powerful package manager for windows. However, I already installed mkdocs a few month ago. To my mind, chocolatey don’t help this much.

First things first : Installing Python

Before installing mkdocs. I need to install python and pip (Python package manager).

Firstly, I downloaded the python installer here. I choosed the windows version. I runned the installer and complete the installation process. Before isntalling a sofware on windows, consider these tips :

  1. Windows install software in C:/Users/username/Appdata when you choose “install for this user only”
  2. Windows install software in C:/ProgramFiles when you choose “install for all users”
  3. Windows is not very clever at managing environement Path… Adding useful directory to path manually is often required
  4. Windows is not very clever :p

When you run the python installer, select custom installation. Then check these option :

Python installation tutorial

When suscessfully installed python, we have to install mkdocs and its dependecies. You’re python installation folder should be added to the environment variable. If not, please add it manually, there is a very good tutorial here

To check if everything is installed properly, open a terminal.

Tips : You can open terminal using the file explorer, in the filepath bar, type cmd and hit enter This is very convenient for opening terminal in your curent working directory.

In the terminal type python --version Expected result :

$ python --version
Python 3.9.1

If the terminal give you an error, check if you installed python properly and check if python is added to PATH enviroment variable. If you got the version, you’re ready to go.

We may also check if pip is installed. let’s try :

$ pip --version
pip 20.2.3 from c:\program files\python39\lib\site-packages\pip (python 3.9)

If you don’t have this result, don’t panic (I did), It may be the PATH variable messing with you once again. In your python installation folder, you should have a directory named “Scripts”. Make sure this directory is also in your PATH variable.

In other words, you should have these two lines :

C:\Program Files\Python39\
C:\Program Files\Python39\Scripts\

Pip should work properly now…

Tips : to upgrade pip, consider using pip install --upgrade pip

Installing Mkdocs

Installing mkdocs is easier thanks to pip. Pip is the python package provider. It is in charge of installing everything you need automatically (And it is very good at it). To install mkdocs, juste type :

pip install mkdocs

I never had problems running this command. If you does, please check the official mkdocs issue tracker here.

To run our documentation site locally we will need a few more package. Make sure to install mkdocs-material and mkdocs-git-revision-date-localized-plugin. pip install mkdocs-material pip install mkdocs-git-revision-date-localized-plugin

Mkdocs should be installed properly, let’s move to git installation.

Installing Git

I’m not an expert in version control but I have good overview of what git & gitlab help to do. I have a mechanical engineering background, but I develop programs for a while now. For some reason, I never heard about Git at school… Mechanical engeenering (french) teacher seems to be affraid of whatever computer programm you use ! I was probably one the few student of my degree to host CAD file on git to optimize the development process. Anyway, I love git and it’s way more convenient than whatever other version control methods I tested !

To install Git on windows, I downloaded git installer from here

Here is the installation process :

Git installation

To check git installation type git --version in a terminal. Expected result :

$ git --version
git version 2.30.0.windows.2
Once again mind your PATH variable ! Adding git to your PATH should be easy now.

Once you have git installed, you’re able to download your distant project ! To download your documentation site project we will clone it.

Vocabulary : A git project is called a repository

Using SSH authentification

When working on documentation I must login to gitlab very often (each time I want to bring my changes online). It is possible to use git only using standard passwors / login methods… or you can use SSH !

Ssh-key security is a very good way to authentify everywhere. ssh-key are based on asymetric cryptography protocol. Which mean that when you generate a key, the program gives you a public key which can be shared with every one, and a private one which shouldn’t. When a website want to check you’re identity it can send a bunch of data encrypted using your public key, then to decrypt the data, the private key is needed, in theory only you’re computer should be able to decrypt the data and autentify.

Open a terminal and type :

ssh-keygen
this will generate your own key. It is recommended to use a passphrase to increase the complexity of the key (but it is not mandatory). on Windows you can access to your public key at thuis path :

%userprofile%/.ssh/id_rsa.pub

Copy the whole content on this file and add it to your gitlab account. Go to your settings > SSH key and paste the content of the key.

Then you should be able to git clone, git commit, git push without typing your password ! Seems obvious but don’t share your private key to anyone !

Clonning a repository

To clone my repo, I used this command :

$ git clone git@gitlab.fabcloud.org:academany/fabacademy/2021/labs/lamachinerie/students/jules-topart.git
Cloning into 'jules-topart'...
remote: Enumerating objects: 150, done.
remote: Counting objects: 100% (150/150), done.
remote: Compressing objects: 100% (113/113), done.
remote: Total 1044 (delta 65), reused 96 (delta 35), pack-reused 894
Receiving objects: 100% (1044/1044), 40.77 MiB | 4.46 MiB/s, done.
Resolving deltas: 100% (456/456), done.

This will create a floder contaning all your documentation site. Browse wisely before running the command.

Info

The git clone command can be use trough ssh or https depending on the URL you use. I cloned over SSH howerver the port 22 in sometimes blocked in university. You can use https as well but your password will be asked… (You can use port 443 instead or port 22 using the alternative ssh port of Gitlab)

When you’ve clonned the repo, use mkdocs serve to start the local server. your site should be accessible on 127.0.0.1:8000

Error

If the command didn’t worked for you, try this :

python -m mkdocs serve

If this one does the job, pip installed mkdocs in a folder which isn’t in your path. Consider adding %appdata%/Python/Python39/Scripts to your path. The previous command should work.

When your docs is updated and you’re ready to post, use git add --all to add your changes to the next commit, then use git commit -m "Your commit message"

Note : I personnaly use the commit convention from here to name my commits.

When you’re ready to send your changes (and absolutely sure of what your doing) Type git push to send everything to your gitlab page. The page should build and after a few moment be updated !

Visual Studio code

Just one more thing. I’m using visual studio code to write, code, git my documentation. If you don’t already know this great tools check this link

VSCode offer the ability to install a lot of additionnal package from Text editing tool to IoT flashing tools

I like It !

This page was written using vscode ;)


Last update: September 23, 2021