.. Glaciation documentation master file, created by
   sphinx-quickstart on Wed Apr 12 14:03:23 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.
.. highlight:: sh

*************************
Download and Installation
*************************

Overview
========

 0. Install `Python 3.11 (32bit) <https://www.python.org/downloads/>`_.
 1. `Download and install Glaciation. <#installing-glaciation>`_ 

Glaciation versions
===================

.. note:: Glaciation 1.0.0 only supports Python 3.11 (32 bit)! A non official version exists for Python 2.7 (32 bit).

+------------------+-------+-------+----+
| Glaciation versions   | 0.0.0 | 1.0.0 |
+==================+=======+=======+====+
| Python 3.11  (32 bit) |   ❌  |  ✅   |
+------------------+-------+----+-------+
| Python 3.11  (64 bit) |   ❌  |  ❌   |
+------------------+-------+-------+----+
| Python 2.7   (32 bit) |   ✅  |  ❌   |
+------------------+-------+-------+----+
| Python 3.X-3.10 (any) |   ❌  |  ❌   |
+------------------+-------+-------+----+
 
Installing Glaciation
=====================

The following steps describe how to install (or update) Glaciation itself.


.. note::

   Available only for Windows platform.

Make sure you have Python installed before you go on.

Where to get it
---------------

The source code is currently hosted on GitLab at:
https://gitlab.cafpower.com/glaciation/py-glaciation

Binary installers for the latest released version are available at the **Scman->Cautto->glaciation.**

The list of changes to glaciation between each release can be found in Scman as well.
For full details, see the commit logs at https://gitlab.cafpower.com/glaciation/py-glaciation.

.. seealso::

   Installing the package in a virtual environment is recommended: `https://docs.python.org/3/library/venv.html`

   | $ pip install virtualenv
   | $ path_to_python/Scripts/virtualenv -p path_to_python/python.exe venv


Use pip::

$ pip install glaciation-X.X.X-py3-none-any.whl


 
From source
-----------

.. index::
   single: Git, repository

If you always want the latest version of Glaciation with all new the features and bugfixes (but slightly less stable), you can install Glaciation from its Git repository.


1. Check out a clone of Glaciations's repository with `git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_::

   $ git clone git@gitlab.cafpower.com:glaciation/py-glaciation.git
   $ cd py-glaciation

2. Install Glaciation using `pip <https://docs.python.org/dev/installing/index.html>`_:: 

   $ pip install .

3. If you used Git, you can always update to the latest version afterwards::

   $ git pull
   $ pip install .


Build a new wheel file
======================
You can always change the source code by your own and build a new wheel file.

Before creating this file, you will need to install a couple of Python packages.
   $ pip install wheel setuptools

And then
   $ python setup.py bdist_wheel

Build the documentation offline
===============================

The Glaciation project's documentation is written using reStructuredText (files \*.rst) and can be built using
the `Sphinx <http://www.sphinx-doc.org/>`_ python library. The official online version is available
on `readthedocs <http://glaciation.aminlan.com/docs/>`_.

HTML version
------------
The instructions to build the HTML version are: ::

   (activate a virtualenv)
   pip install sphinx
   cd doc/glaciation
   make html

You can now open the resulting HTML file ``_build/html/index.html`` in your favorite web browser.

To use the ReadTheDocs' template, you will have to install the corresponding theme with: ::

   pip install sphinx_rtd_theme