Since Rocky we use ReadTheDocs for the User Guide

Prepare your machine (if needed)


Make sure you have git and make installed.


The simplest thing, then, is to prepare a (recent) python virtual environment using conda:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
sh ./Miniconda3-latest-Linux-x86_64.sh


Once activated the 'base' environment or if you created and activated a new one, within the conda environment:

git clone git@github.com:CloudVeneto/CVUserGuide.git
cd CVUserGuide
python -m pip install -r source/requirements.txt


Please note: you might clone a copy of the documentation using the 'https' protocol but you won't be able to push your changes afterwards. Please be sure you can clone the repo using the 'SSH' protocol as above (e.g. you are entitled to push your commits to the repo).

Create your local copy of the documentation


cd CVUserGuide
make html
Check in a browser build/index.html

Update the existing documentation

The following operations must be done each time it is necessary to update the user guide. They can be done as normal user.


Update the sources from git:

cd CVUserGuide
git pull


Make your changes. Also edit the file source/conf.py increasing the last number (the one after the ".") for "release" and "version".

Try to build:

make html
Check in a browser build/index.html


If you are happy, commit and push:

git add <modified files>
git commit -a
git push


In case you are trying to push using username and password you will receive an error like:

remote: Support for password authentication was removed on August 13, 2021.
remote: Please see https://docs.github.com/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls for information on currently recommended modes of authentication.

In that case ensure in .git/config the remote "origin" url is set to

url = git@github.com:CloudVeneto/CVUserGuide.git

and retry.