Skip to content

Upgrade to latest template

If the source template get new features, like improving plugins.py script, you might want to get them. To do so is as easy as installing the documentation. This is done using the script setup.sh with the option -u. Below is a recall of the usage of the script

Synopsis of setup.sh

./setup.sh [-u|--upgrade] [-s|--subrepo] [-h|--help] -r|--repo-url REPO_URL

Description

This script will install/upgrade set of scripts and files to create and manage documentation rendered using mkdocs.

If directory is already using mkdocs and user does not provide -u|--upgrade options, an error will be shown and nothing will be done.

If user does not provide REPO_URL from which download the template, i.e. using option -r|--repo-url REPO_URL, then an error will be prompt and the script will exit.

Options

Available options are:

  • -u,--upgrade : Upgrade the current mkdocs documentation to the latest template version.

  • -s,--subrepo : Specify the current repo is a subrepo that will be merge into another main project using mkdocs-monorepo plugin.

  • -r,--repo-url : URL of the repo from which the template will be downloaded.

  • -h,--help : Print the help.

How to upgrade

This is done by using the option -u of the script setup.sh. Using this option, the script will compare last version with old version of each files. If they have changed, backup the old version, to avoid losing content in case of error and then upgrade the files to the latest version.

# 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
# NOTE THE USAGE OF THE `-u` OPTION
/tmp/setup_mkdocs.sh -u -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
# NOTE THE USAGE OF THE `-u` OPTION
curl -sfL \
  https://framagit.org/rdeville.public/my_programs/mkdocs_template/-/raw/master/setup.sh \
  | bash -s -- \
    -u -r https://framagit.org/rdeville.public/my_programs/mkdocs_template

This will automatically upgrade the content of your documentation from the template to its latest version.


Last update: May 6, 2021