Merge pull request #35 from gramaziokohler/install-docs

Add install docs page

README.md

@@ -1,4 +1,4 @@
-# AI-eXtended Design (AIXD): Grasshopper plugin
+# ARA: AIXD Grasshopper plugin
 
 Grasshopper plugin for the AIXD toolkit.
 
@@ -11,24 +11,30 @@ Grasshopper plugin for the AIXD toolkit.
 - flask
 
 #### Latest stable version
+
 Install `aixd_ara` using `pip`
-```
+```bash
 pip install aixd_ara
 ```
 
 Install `aixd_ara` using `conda`:
-```
+```bash
 conda install -c conda-forge aixd_ara
 ```
 
+Install the plugin in Rhino/Grasshopper using the following command:
+```bash
+python -m compas_rhino.install -v 7.0
+```
+
 **Note**: It is recommended to use virtual environments to manage the dependencies of your projects. If you are using 
 `conda`, you can create a new environment with `conda create -n myproject python=3.9` and then activate it with
 `conda activate myproject` before installing `aixd_ara`.
 
 #### Latest unstable version
 
 Install the latest version using `pip` from the git repository:
-```
+```bash
 pip install --upgrade git+https://github.com/gramaziokohler/aixd_ara.git
 ```
 
@@ -41,7 +47,7 @@ git clone https://github.com/gramaziokohler/aixd_ara.git
 cd aixd_ara
 ```
 
-Then, install using conda, to install all the dependencies into a new environment called `aixd_gh`:
+Then, use conda to install all the dependencies into a new environment called `aixd_ara`:
 ```bash
 conda env create -f environment.yml
 ```

docs/installation.rst

@@ -1,3 +1,120 @@
 ********************************************************************************
 Installation
 ********************************************************************************
+
+This page provides a guide for installing the ``ARA`` plugin on your system.
+The plugin can be installed using an installer, or a package manager for Python such as ``pip`` or ``conda``.
+
+The following instructions will guide you through each method.
+Alternatively, you can clone the ``aixd_ara`` source code directly from
+our `repository <https://github.com/gramaziokohler/aixd_ara>`_.
+
+Installer
+=========
+
+The installer is the easiest way to install the plugin on your system
+for the majority of users.
+
+Windows Users
+-------------
+
+* Download `the ZIP file <https://github.com/gramaziokohler/aixd_ara/raw/main/install.zip>`_.
+* Extract it to any folder of your preference.
+* Double-click the `install.cmd` file to start the installation.
+
+Mac Users
+---------
+
+On Mac, it's not necessary to download the installer. Instead,
+open the Terminal application of your mac, copy & paste the following
+command, and press Enter:
+
+.. code-block:: bash
+
+    curl -s https://github.com/gramaziokohler/aixd_ara/raw/main/install.bash | bash
+
+
+Installation using pip
+======================
+
+The most popular package manager for Python is ``pip``.
+You can use it to install packages from the Python Package Index and other indexes.
+
+**Step 1: Update pip**
+
+It is good practice to ensure that you are using the latest version of ``pip``.
+To update ``pip``, run the following command:
+
+
+.. code-block:: bash
+
+    python -m pip install --upgrade pip
+
+**Step 2: Install plugin**
+
+To install `ara_aixd` using ``pip``, execute the following command:
+
+.. code-block:: bash
+
+    pip install ara_aixd
+
+And then install the plugin in Rhino/Grasshopper using the following command:
+
+.. code-block:: bash
+
+    python -m compas_rhino.install -v 7.0
+
+
+Installation using conda
+========================
+
+``conda`` is an open-source package management system and environment
+ management system that runs on Windows, macOS, and Linux.
+ It’s very popular in the realm of scientific computing.
+
+**Step 1: Create a conda environment (Optional)**
+
+It's often beneficial to create a new environment for your project. This can be done using the following command:
+
+.. code-block:: bash
+
+    conda create --name project_name python=3.x
+
+
+Replace *project_name* with your desired environment name and *3.x* with the
+specific version of Python you want to use.
+This package requires python 3.9 or a higher.
+
+Activate the new environment by running:
+
+.. code-block:: bash
+
+    conda activate project_name
+
+**Step 2: Install plugin**
+
+To install ``aixd_ara`` in your ``conda`` environment, use the following command:
+
+.. code-block:: bash
+
+    conda install -c conda-forge aixd_ara
+
+Finally, install the plugin in Rhino/GH using the following command:
+
+.. code-block:: bash
+
+    python -m compas_rhino.install -v 7.0
+
+
+Verify installation
+===================
+
+After installation, you can verify that the plugin has been successfully installed by running:
+
+.. code-block:: bash
+
+    python -c "import aixd_ara; print(aixd_ara.__version__)"
+
+
+If everything worked out correctly, the version of the installed plugin will be printed on
+the screen, and you can start using the plugin in your projects.

environment.yml

@@ -1,4 +1,4 @@
-name: aixd_gh
+name: aixd_ara
 channels:
     - conda-forge
 dependencies:

install.bash

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+while true; do
+    read -n 1 -p "Select Rhino version (7, 8, or Q to quit):" RHINO_VERSION
+    printf "\n";
+    case $RHINO_VERSION in
+        7* ) break;;
+        8* ) break;;
+        [Qq]* ) exit;;
+        * ) printf "Invalid Rhino version, please choose either 7 or 8.\n";;
+    esac
+done
+
+CONDA_HOME=$HOME/miniconda
+CONDA_BIN=$CONDA_HOME/condabin
+CONDA_ENV_NAME=aixd_ara
+
+printf "[√] Starting ARA installation…\n"
+
+printf "[ ] Checking conda…"
+
+if ! command -V conda &> /dev/null
+then
+    printf "\r[x] Conda not found, we will install Miniconda\n"
+	printf "[ ] Installing miniconda (Python distribution)…"
+	# curl https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -o ./miniconda.sh &> /dev/null
+	curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ./miniconda.sh &> /dev/null
+	bash ./miniconda.sh -b -u -p $CONDA_HOME &> /dev/null
+	printf "\r[√] Installing miniconda (Python distribution)…\n"
+
+	printf "[ ] Configuring miniconda for first use…"
+	$CONDA_BIN/conda init bash &> /dev/null
+	source $HOME/.bash_profile &> /dev/null
+	printf "\r[√] Configured miniconda for first use successfully\n"
+else
+	CONDA_HOME=$(dirname $(dirname $CONDA_EXE))
+    printf "\r[√] Conda command found!\n"
+fi
+
+if { conda env list | grep $CONDA_ENV_NAME; } >/dev/null 2>&1; then
+    printf "[√] Virtual environment already exists! ($CONDA_ENV_NAME)\n"
+else
+    printf "[√] Virtual environment not found, will create it now…\n"
+
+    printf "[ ] Creating virtual environment…"
+    conda create -c conda-forge -n $CONDA_ENV_NAME aixd aixd_ara compas flask python=3.9 -y &> /dev/null
+    printf "\r[√] Created virtual environment '$CONDA_ENV_NAME' successfully\n"
+fi
+
+printf "[ ] Activating virtual environment…"
+source $CONDA_HOME/bin/activate $CONDA_ENV_NAME
+printf "\r[√] Activated virtual environment successfully\n"
+
+printf "[√] Activating environment '$CONDA_ENV_NAME' for Rhino…\n"
+python -m compas_rhino.install -v $RHINO_VERSION.0
+printf "\r[√] Successfully installed ARA on Rhino\n"

install.cmd

@@ -0,0 +1,140 @@
+@ECHO OFF
+SETLOCAL EnableExtensions EnableDelayedExpansion
+
+REM The following lines are courtesy of Windows' magnificent support for shell programming:
+REM https://superuser.com/a/1166728
+for /f %%a in ('copy /Z "%~dpf0" nul') do set "CR=%%a"
+for /f %%a in ('"prompt $H&for %%b in (0) do rem"') do set "BS=%%a"
+
+REM Retrieve current code page, before changing it
+for /f "usebackq tokens=4" %%i in (`chcp`) do (
+  set _PREV_CHCP=%%i
+)
+
+SET CONDA_PATH=%UserProfile%\Miniconda3
+SET CONDA_ENV_NAME=aixd_ara
+
+REM Switch code page, so that we can print extended ASCII
+CHCP 65001 >nul
+
+:select_rhino_version
+set RHINO_VERSION=
+set /p RHINO_VERSION="Select Rhino version (7 or 8) [7]:"
+if not "%RHINO_VERSION%"=="" set RHINO_VERSION=%RHINO_VERSION:~0,1%
+if "%RHINO_VERSION%"=="" set RHINO_VERSION=7
+if "%RHINO_VERSION%"=="7" goto valid_rhino_version
+if "%RHINO_VERSION%"=="8" goto valid_rhino_version
+
+ECHO Invalid Rhino version, please choose either 7 or 8.
+GOTO select_rhino_version
+
+:valid_rhino_version
+
+<nul set /p"=[√] Starting ARA installation..."
+ECHO.
+
+:check_conda_presence
+<nul set /p"=[ ] Checking conda..."
+WHERE conda >nul 2>&1
+
+IF %ERRORLEVEL%==0 (
+    <nul set /p"=!BS!!CR![√] Conda command found!"
+    GOTO use_existing_conda
+)
+IF %ERRORLEVEL%==1 (
+    <nul set /p"=!BS!!CR![x] Conda not found, we will install Miniconda"
+)
+
+ECHO.
+
+<nul set /p"=[ ] Installing miniconda (Python distribution)..."
+CALL curl -S -s -O https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe
+IF %ERRORLEVEL% neq 0 GOTO miniconda_download_failed
+SET CONDA_COMMAND=%CONDA_PATH%\condabin\conda
+
+REM The last argument must NOT be quoted according to the conda docs, and that works even for paths with spaces in them
+START /wait /min "Starting miniconda installation..." "Miniconda3-latest-Windows-x86_64.exe" /InstallationType=JustMe /S /D=%CONDA_PATH%
+IF %ERRORLEVEL%==2 (
+    <nul set /p"=!BS!!CR![√] Miniconda seems to be already installed, will skip step and continue..."
+    ECHO.
+    GOTO compas_install
+)
+IF %ERRORLEVEL% neq 0 GOTO miniconda_install_failed
+<nul set /p"=!BS!!CR![√] Installing miniconda (Python distribution)..."
+ECHO.
+
+:compas_install
+<nul set /p"=[ ] Looking for virtual environment (%CONDA_ENV_NAME%)..."
+CALL "%CONDA_COMMAND%" activate %CONDA_ENV_NAME% >nul 2>&1
+IF %ERRORLEVEL%==0 (
+    <nul set /p"=!BS!!CR![√] Virtual environment already exists! (%CONDA_ENV_NAME%)"
+    ECHO.
+    GOTO compas_install_to_rhino
+)
+<nul set /p"=!BS!!CR![√] Virtual environment not found, will create it now...                                     "
+ECHO.
+
+<nul set /p"=[ ] Creating virtual environment..."
+CALL "%CONDA_COMMAND%" create -c conda-forge -n %CONDA_ENV_NAME% aixd aixd_ara compas flask python=3.9 -y >nul 2>&1
+<nul set /p"=!BS!!CR![√] Created virtual environment '%CONDA_ENV_NAME%' successfully"
+ECHO.
+
+:conda_activate_virtual_env
+ECHO ON
+<nul set /p"=[ ] Activating virtual environment..."
+CALL "%CONDA_COMMAND%" activate %CONDA_ENV_NAME%
+IF %ERRORLEVEL% neq 0 GOTO conda_activate_failed
+<nul set /p"=!BS!!CR![√] Activated virtual environment successfully"
+ECHO.
+
+:pip_install_deps
+<nul set /p"=[ ] Installing pip tools..."
+python -m pip install aixd_ara-0.1.0-py2.py3-none-any.whl -q
+@REM python -m pip install black flake8 isort pytest rhino-stubs -q
+IF %ERRORLEVEL% neq 0 GOTO pip_install_deps_failed
+<nul set /p"=!BS!!CR![√] Installed pip tools successfully"
+ECHO.
+
+:compas_install_to_rhino
+<nul set /p"=[√] Activating environment '%CONDA_ENV_NAME%' for Rhino..."
+ECHO.
+<nul set /p"=[√] Environment location: %CONDA_PREFIX%"
+python -m compas_rhino.install -v %RHINO_VERSION%.0
+<nul set /p"=[√] Successfully installed ARA on Rhino"
+ECHO.
+GOTO end_of_installer
+
+:use_existing_conda
+for /f "tokens=* delims=" %%a in ('where conda') do (
+    set "CONDA_COMMAND=%%a"
+    goto found_conda
+)
+:found_conda
+ECHO.
+GOTO compas_install
+
+:conda_activate_failed
+ECHO.
+ECHO Could not activate virtual environment. Exiting.
+GOTO end_of_installer
+
+:pip_install_deps_failed
+ECHO.
+ECHO Could not install development tools. Exiting.
+GOTO end_of_installer
+
+:miniconda_install_failed
+ECHO.
+ECHO Could not install miniconda. Exiting.
+GOTO end_of_installer
+
+:miniconda_download_failed
+ECHO.
+ECHO Could not download miniconda. Exiting.
+GOTO end_of_installer
+
+:end_of_installer
+SET _ERRORLEVEL=%ERRORLEVEL%
+CHCP %_PREV_CHCP% >nul
+PAUSE
+EXIT /B %_ERRORLEVEL%

src/aixd_ara/__init__.py

@@ -0,0 +1,5 @@
+__author__ = ["Aleksandra Apolinarska"]
+__copyright__ = "Copyright (c) 2023-2024 ETH Zurich, Gramazio Kohler Research"
+__license__ = "MIT License"
+__email__ = "[email protected]"
+__version__ = "0.1.0"