Skip to content
Snippets Groups Projects
Verified Commit c60574f9 authored by Romain Deville's avatar Romain Deville
Browse files

:pencil: Add README.md

parent 6b3a5113
No related branches found
No related tags found
No related merge requests found
README.md 0 → 100644
<div align="center" style="text-align: center;">
<!-- Project Title -->
<a href="https://framagit.org/rdeville.public/my_programs/mkdocs_template">
<img src="docs/assets/img/meta/mkdocs_template_logo.png" width="100px">
<h1>Mkdocs Template</h1>
</a>
<!-- Project Badges -->
[![License][license_badge]][license]
[![Build Status][build_status_badge]][build_status]
--------------------------------------------------------------------------------
Template to easily setup and managed [mkdocs][mkdocs] documentation in folder
to have homogenous documentation.
--------------------------------------------------------------------------------
<b>
IMPORTANT !
Main repo is on [ Framagit][repo_url].<br>
On other online git platforms, they are just mirror of the main repo.<br>
Any issues, pull/merge requests, etc., might not be considered on those other
platforms.
</b>
</div>
--------------------------------------------------------------------------------
[repo_url]: https://framagit.org/rdeville.public/my_programs/mkdocs_template
[license_badge]: https://img.shields.io/badge/License-MIT%2FBeer%20Ware-blue?style=flat-square&logo=open-source-initiative
[license]: LICENSE
[build_status_badge]: https://framagit.org/rdeville.public/my_programs/mkdocs_template/badges/master/pipeline.svg?style=flat-square&logo=appveyor
[build_status]: https://framagit.org/rdeville.public/my_programs/mkdocs_template/commits/master
## Table of Content
* [Introduction](#introduction)
* [Usage](#usage)
* [Project Documentation](#project-documentation)
## Introduction
Since some times now, I use [mkdocs][mkdocs] to write documentation of my
projects.
While [mkdocs][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:
```bash
# 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:
```bash
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][online_doc].
<!-- BEGIN MKDOCS TEMPLATE -->
<!--
WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !
Modified content will be overwritten when updating
-->
## Project Documentation
The complete documentation of the project can be accessed via its [Online
Documentation][online_doc].
If, for any reason, the link to the [Online Documentation][online_doc] 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:
```bash
# 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][mkdocs] in the python virtual environment:
```bash
pip3 install -r requirements.docs.txt
```
Now you can easily render the documentation using [mkdocs][mkdocs] through the
usage of the following command (some logs will be outputed to stdout):
```bash
# 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].
[localhost]: https://localhost:8000
[mkdocs]: https://www.mkdocs.org/
<!-- END MKDOCS TEMPLATE -->
[online_doc]: https://docs.romaindeville.fr/rdeville.public/my_programs/mkdocs_template/index.html
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment