Updating the docs

This online documentation is generated using mkdocs and is hosted on a Github Pages.

The following procedure explains how to build this documentation on your own system, and how to upgrade the live one.

Local Setup

In order to build the local version of this documentation, the mkdocs package is required:

$ pip install mkdocs
$ mkdocs -V
  mkdocs, version 1.1.2 from /usr/lib/python3.8/site-packages/mkdocs (Python 3.8)

To get the last version of the documentation's file, clone the Cerberus Sandbox public GitHub repository in one of your local folder:

$ git clone https://github.com/Cerberus-Sandbox/cerberus-sandbox.github.io

The GitHub repository is composed of two branches: main and master. The first one holds the raw mkdocs files, and the second one is the compiled version of the website used by GitHub to host the live instance.

You should never edit the master branch by hand. Even in a local setup.

Now that you hold a local copy of the documentation website, simply run mkdocs build to generate the compiled HTML pages.

The entrypoint of the local setup is located in site/index.html.

If you want to edit the live content, or if you need to add a new page, everything will be done in the docs/ folder.

A typical architecture can be resumed by the following:

 docs/
 ├── I. Subsection n°1
 │   ├── 1. Doc 1.md
 │   ├── 2. Doc 2.md
 │   └── 3. Doc 3.md
 └── II. Subsection n°2

Each folder holds a subsection of the documentation, and each markedown file stores the actual content of the page.

You can refer to the following cheatsheet to edit your markedown file: www.markdownguide.org/cheat-sheet/

Upgrading the live version

Whenever the local content is ready to go, you can use the automatic script ship-to-prod.sh to push the new content on GitHub and rebuild the mkdocs instance, or choose to do it by hands.

The script is located at the root folder of the cerberus-sandbox repository.

You can choose to pass a short description of your modification to the script, as a string value, for a better understanding of each commit:

$ chmod +x ./ship-to-prod.sh
$ ./ship-to-prod.sh "index update + typo"

And that's it, shortly after that, the upgraded version of the documentation website should be up and running.

For the manual process, two steps are needed:

First, the mkdocs sources need to be saved in the main branch:

$ git pull
$ git checkout main
$ git add docs/*
$ git add mkdocs.yml
$ git commit -m "your commit message"
$ git push

If you don't push to the main branch, the next modifications will erase yours, and nobody will be able to track and download your modifications.

Then, the mkdocs sources can be compiled and shiped to the github master branch:

$ mkdocs gh-deploy --force --remote-branch master

And that's it. Remember that you'll have to wait several minutes to see your updates on the live page !

Pages layout

Every entry in the Documentation need to follow the same layout. The goal is to keep everything consistent with a set of basics rules for the contributors. This section is basically a list of rules to follow in order to fully integrate your page in this project.

A page need to have one (and only one) title, and that title should match the name of the file, even if it contain some special characters or some spaces.

 ## This is a title 
 It match the file 'This is a title.md'

When possible, split your page with sub-sections. It will help the navigation in the side menu, and a quick way to find information in a large page.

 ### This is a sub-section

At the beginning of the page, a short description should be made. This can be a sum-up of the page, or a way to identify what the reader will learn.

When the name of a script, a program file, or a path is used, put it in back-quotes:

 `python` is the best interpreted language

Do not write code outside the markedown code blocks:

 ```python
   print("this is code")
 ```

Be as precise as possible when writting about practical technical stuff, and as theoretical as possible when writting about some high-level concepts. Generaly speaking, thoses two part should be keept in separated pages in different sections. But be carrefull not to be too precise. This is a documentation about the Cerberus-Sandbox, we don't need to re-write technical documentation about already-existing tools.

Even in a technical installation process, don't blindly list commands to copy and paste. Explain everything that is relevant.

Always use relative path, except if the path that you are talking about is standard for everyone.

Do not use any hardcoded IP or username in your pages.

Do not write down any personnal credentials or API keys.