Mkdocs Template

---

Template to easily setup and managed mkdocs documentation in folder to have homogenous documentation.

---

IMPORTANT !

Main repo is on  Framagit.
On other online git platforms, they are just mirror of the main repo.
Any issues, pull/merge requests, etc., might not be considered on those other platforms.

Table of Content

• Introduction
• Usage
• Project Documentation

Introduction

Since some times now, I use mkdocs to write documentation of my projects.

While mkdocs is a really usefull software allowing me to write clean and clear documentation in markdown and render it as static website, I was tired to always copy/paste same configuration accross all my projects documentations.

Even worst, when I decide to change some minor things (such as color palettes), I had to go to each projects and for each project I had to replace manually every time the same two configuration lines.

This project aims is to ease the management of documentation configuration by allowing to create a template and easily setup or upgrade it to a newer version.

Usage

Assuming you want to use this really basic template. In a repo in which you want to create a documentation, type the following commands:

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
# First download the setup script into a temporary folder
wget \
   https://framagit.org/rdeville.public/my_programs/mkdocs_template/-/raw/master/setup.sh \
   -O /tmp/setup_mkdocs.sh
# Then read the content of the script with your favorite editor
vim /tmp/setup_mkdocs.sh
# If you are confident with what the script does, make it executable and run it
chmod +x /tmp/setup_mkdocs.sh
/tmp/setup_mkdocs.sh -r https://framagit.org/rdeville.public/my_programs/mkdocs_template

Or if you already read the content of the script setup.sh at the root of this repo, previous commands can be done in online:

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
# You can get the content of the script setup.sh via curl and pipe it into bash
curl -sfL \
   https://framagit.org/rdeville.public/my_programs/mkdocs_template_rdeville/-/raw/master/setup.sh \
   | bash -s -- -r https://framagit.org/rdeville.public/my_programs/mkdocs_template_rdeville

This will automatically create the folder docs with basic pages and the following files:

• mkdocs.yml
• requirements.docs.in
• requirements.docs.txt

What you will now have to do is :

• Copy the provided template file docs/_data/template/repo.tpl.yaml into docs/_data/repo_name.yml such as repo_name is the slug of your repo (for instance slug of mkdocs template is mkdocs_template and slug of docs.domain.tld project is docs_domain_tld_project).
• Edit this new file docs/_data/repo_name.yml, especially, do not forget to change the key repo_name in the file accordingly to your repo slug.

You are ready now to render you documentation:

mkdocs serve

This is the basic usage of the template, but you might want to provide your own configuration (such as other color palette or add a default license). This will be explain in the Online Documentation.

Project Documentation

The complete documentation of the project can be accessed via its Online Documentation.

If, for any reason, the link to the Online Documentation is broken, you can generate its documention locally on your computer (since the documentation is jointly stored within the repository).

To do so, you will need the following requirements:

• Python >= 3.8
• Pip3 with Python >= 3.8

First setup a temporary python virtual environment and activate it:

# Create the temporary virtual environment
python3 -m venv .temporary_venv
# Activate it
source .temporary_venv/bin/activate

Now, install required dependencies to render the documentation using mkdocs in the python virtual environment:

pip3 install -r requirements.docs.txt

Now you can easily render the documentation using mkdocs through the usage of the following command (some logs will be outputed to stdout):

# Assuming you are at the root of the repo
# If there is a `mkdocs.local.yml`
mkdocs serve -f mkdocs.local.yml
# If there is no `mkdocs.local.yml`, only `mkdocs.yml`
mkdocs serve

You can now browse the full documentation by visiting [http://localhost:8000][localhost].