Improve ease of installation with improved instructions and template workflow+database

[nelliputkonen]

First of all, the current SpineOpt installation instructions offer many choices and it doesn't guide the user to pick the easiest one. Secondly, the installation leaves the user in a point where they have to build their own workflow and start from an empty database. This will be necessary e.g. when 30 students of Tampere Uni will have to install SpineOpt.

This could be improved by:

1. Improving the installation instructions so that it links to the easiest way of installing Toolbox: https://spine-tools.github.io/Downloads/ (and just mention that for other ways of installing, see Toolbox instructions). Then guiding the user to install SpineOpt like described in these Toolbox instructions https://spine-toolbox.readthedocs.io/en/latest/how_to_run_spineopt.html (they are simpler than current SpineOpt instructions). When issue https://github.com/spine-tools/Spine-Toolbox/issues/2798 is solved, better still would be to guide users to use bundle installation of SpineOpt and Julia via Toolbox.
2. The installer should not be left with an empty workflow editor, rather a ready template workflow could be provided as direct download from git (or even be available with the SpineOpt+Julia bundle if that's possible). The workflow (or optionally tutorial pages) could include a template database, that already has working basic temporal and stochastic settings.

This type of installation procedure would significantly reduce the threshold of getting started with using SpineOpt.

[tarskul]

At one point I attempted myself to make a more streamlined process. I got close but I wasn't confident that it would work for everyone and that is why I haven't put them online yet.

But since it is relevant here, I thought I'd mention it and share the installation bash script I've got so far (on linux you have to change python to python3).

The idea is that you simply run the script and everything would be ready to use (except for one setting in SpineToolbox that needs to be set manually, i.e. pointing to the created julia environment). It could be the first step towards a real installer.

Currently you may run into errors with the script ("it works on my machine") but you can still use it as a guideline for what needs to be done.

I had the intention to make a corresponding readme file with the explanation and make a separate repository for these files called 'spine-installation-tools'.

#!/bin/bash
#chmod +x ~/spinetools/v08_install_spinetools.sh
# check whether python, git and julia are installed; python may be needed to changed to python depending on your system
python --version
git --version
julia --version

# user settings: install directory, environment names
path_spinetools=$(dirname $0)
path_envs=environments
env_python=penv_v08
# the julia settings need to be adjusted directly in the code (see further below)

# download files from git
cd $path_spinetools
git clone https://github.com/spine-tools/Spine-Toolbox.git
git clone https://github.com/spine-tools/SpineInterface.jl.git
git clone https://github.com/spine-tools/SpineOpt.jl.git

# branch
#cd SpineInterface.jl
#git fetch
#git checkout -b 0.8-dev origin/0.8-dev
#cd ..
#cd SpineOpt.jl
#git fetch
#git checkout -b 0.8-dev origin/0.8-dev
#cd ..
#cd Spine-Toolbox
#git fetch
#git checkout -b 0.8-dev origin/0.8-dev
#cd ..

# create python environment (for spine toolbox)
mkdir $path_envs
cd $path_envs
python -m venv $env_python
source $env_python/bin/activate
cd ..

# alternatively use a conda environment
#path_conda=~/miniconda3/etc/profile.d/conda.sh
#env_conda=cenv_dev
#source $path_conda
#conda create --name $env_conda python=3.9 -y
#conda activate $env_conda

# install python requirements
cd Spine-Toolbox
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
#python -m pip install -r dev-requirements.txt
cd ..

# create julia environment (for SpineOpt and SpineInterface)
# add packages
# configure PyCall (not always necessary because it should be built with the active python environment)
julia -e '
env_julia = joinpath(@__DIR__,"environments/jenv_v08")
path_python = joinpath(@__DIR__,"environments/penv_v08/bin/python")
path_spineinterface = joinpath(@__DIR__,"SpineInterface.jl")
path_spineopt = joinpath(@__DIR__,"SpineOpt.jl")
import Pkg
Pkg.activate(env_julia)
Pkg.develop(path=path_spineinterface)
Pkg.develop(path=path_spineopt)
Pkg.add(["PyCall", "Documenter", "HiGHS"])
import PyCall
ENV["PYTHON"] = path_python
Pkg.build("PyCall")
println(PyCall.pyprogramname)
'

# manually add julia environment to settings in spine toolbox
#spinetoolbox

# alternatively keep shell open for debugging
$SHELL

[tarskul]

I've updated the getting started section of the documentation:

• Installation: it provides the explanation of 3 ways to install SpineOpt, from easy with low control to hard with full control and it describes better when to use which process.
• recommended workflow: guides the user through a first test run to see whether everything works well. Only a small workflow needs to be setup in Spine Toolbox and we use an existing system without having to build everything yourself.
• trouble shooting: there is a troubleshooting section if you get stuck in the two first steps.

The idea is now that you install and verify your installation of spine tools and that you do not continue unless everything works. Once you are sure that you have a correct installation, you can try the tutorials. With this approach I'm hoping that there is less frustration for first time users.

Does this version make more sense to you @nelliputkonen? Or would you still like to see other improvements to this part?

[nelliputkonen]

Wonderful, thank you @tarskul! I looked through the new sections and they look very good and much clearer now - great work. I will ask some of our new users to test them out step-by-step and send feedback if they find anything to improve!

[tarskul]

Great!