Since Rocky we use ReadTheDocs for the User Guide
Prepare your machine (if needed)
The simplest thing is to prepare a python 3.11 virtual environment using conda:
git clone https://github.com/CloudVeneto/CVUserGuide.git wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh sh ./Miniconda3-latest-Linux-x86_64.sh
Then within the conda environment:
python -m pip install --upgrade --no-cache-dir pip setuptools cd CVUserGuide python -m pip install --upgrade --no-cache-dir pillow \ mock==1.0.1 alabaster>=0.7 commonmark==0.9.1 recommonmark==0.5.0 python -m pip install --exists-action=w --no-cache-dir -r source/requirements.txt pip install 'sphinx_rtd_theme'
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
Download 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.htm
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