Skip to content

Write documentation tutorial

Info

This site is done using the markdown language. It is a simple language that allows you to write text and add some formatting to it. It is compiled with the mkdocs package and the documentation is hosted on github. For full documentation visit mkdocs.org. Then everytime you push your changes on the github repository, the website is updated automatically (using Netlify build command).

Step 0: Git installation on your computer

Linux based systems :

sudo apt install git

For macOS users, if apt doesn't work, you can install homebrew and run instead: 

sudo brew install git

Windows Based systems : git

Git Hub personnal account Create a personnal account on git hub if you don't have one. If you want to edit files on the Quantum Optics documentation you need to be invited by an owner.

Download VSCode

Step 1: clone the github repository on your own workspace

Copy the repository github on your clipboard.

On the VSCode GUI click on the github icon (second item in the top left corner) and then click on Clone Repository and paste the link you just copied.

Now you should see all the files of the team on your VSCode interface on the left part of the screen.

Step 2: create/modify a documentation file and add it to the doclkb page

Go on the repository you cloned on Step 1 and create a file "myfilename.md" (.md stands for the markdown language in which the documents of this page are written) or go on the document you want to modify.

Write the content using markdown.

Step 3: Run the web server locally

You can run locally the website using python. To do so you need to install mkdocs package.

First create a Python virtual environnement using pyenv or preferrably conda. 

conda create web
conda activate
Then install the mkdocs package inside the environnement

conda install mkdocs
pip install -r requirements.txt
Then use the following commands

  • mkdocs serve - Start the live-reloading docs server (this is what you want to do actually)
  • mkdocs build - Build the documentation site.
  • mkdocs -h - Print help message and exit.

Step 4: Push to Github

Once you're done with modifications you can commit the changes you made on the github repository of the team : * Click on the github icon * Enter the message that goes with your commitment (for instance "first commit *username)") * Click on commit next to SOURCE CONTROL title.

If it's the first time you use VSCode with your github account it may ask you to configure your git user.name and user.email. The following command lines should work for any OS :

git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email "MY_NAME@example.com"

Note

The user.name and the user.email have to be identical to the user name and the email you used te create your github account.

If your commit was succesful, you should be able to see your file appear on the Github page of the team as well as on the doclkb page after 30 seconds.