diff --git a/docs/source/figures/install_anaconda_open_base_environment_terminal.png b/docs/source/figures/install_anaconda_open_base_environment_terminal.png new file mode 100644 index 0000000..c8db588 Binary files /dev/null and b/docs/source/figures/install_anaconda_open_base_environment_terminal.png differ diff --git a/docs/source/figures/install_mhkit_python_env_yaml_download.png b/docs/source/figures/install_mhkit_python_env_yaml_download.png new file mode 100644 index 0000000..09bdbbd Binary files /dev/null and b/docs/source/figures/install_mhkit_python_env_yaml_download.png differ diff --git a/docs/source/installation.rst b/docs/source/installation.rst index fd5c981..3f6b741 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -3,15 +3,15 @@ MHKiT-Python Installation ========================= -The following sections includes installation instructions for `MHKiT-Python `_. +The following sections include installation instructions for `MHKiT-Python `_. `MHKiT-Python `_ requires `Python (3.8-3.11) `_ and has several Python package dependencies. -It is recommended to use the `Anaconda Python Distribution `_ to install Python since it includes most of MHKiT-Python's package dependencies. +It is recommended to use `Conda `_ to install Python and MHKiT-Python since it includes most of MHKiT-Python's package dependencies. Requirements ^^^^^^^^^^^^^^^ -`MHKiT-Python `_ requires `Python (3.8-3.11) `_ and has the following Python packages dependencies: +`MHKiT-Python `_ requires `Python (3.8-3.11) `_ and has the following Python package dependencies: * `Xarray `_: used for data storage and analysis * `Pandas `_: used for data storage and analysis @@ -21,49 +21,159 @@ Requirements * `Requests `_: used to get data from websites * `Pecos v0.1.9 `_: used for quality control analysis - Install MHKiT-Python ^^^^^^^^^^^^^^^^^^^^^ -Option 1: PIP Install from Python -"""""""""""""""""""""""""""""""""""" +Option 1: Using Conda +""""""""""""""""""""" -This option is recommended for MHKiT-Python users. -To install MHKiT-Python using `pip `_:: +For most users, `Conda `_ is the preferred choice for installing MHKiT-Python. Conda includes the ``conda`` command line utility to manage Python versions and dependencies within `environments `_. Anaconda provides a standardized Python build environment that is compatible across operating systems, simplifying MHKiT-Python installation and setup for all users. - pip install mhkit -Using this option to install MHKiT-Python will automatically install Pecos. +1. `Install Conda `_ with Anaconda Distribution or Miniconda: + - `Anaconda Distribution `_ is a full featured installer that comes with a suite of packages for data science, as well as Anaconda Navigator, a GUI application for working with conda environments. + - `Miniconda `_ is a minimal installer provided by Anaconda that installs the ``conda`` command line utility and its dependencies. -Option 2: Clone Repository from GitHub -"""""""""""""""""""""""""""""""""""""""""" -This option is recommended for MHKiT-Python developers. -To install MHKiT-Python using `git `_:: - git clone https://github.com/MHKiT-Software/MHKiT-Python - cd mhkit-python - pip install -e . +2. Access the Conda ``base`` environment: + +Using Anaconda Distribution: + +- Launch the "Anaconda Navigator" application + +- Navigate to the "Environments" section + +.. image:: ./figures/install_anaconda_select_environment_section.png + :width: 500 + :alt: Navigating to the Anaconda Navigator "Environments" section + +- Click the play button next to ``base(root)`` and select "Open Terminal" + +.. image:: ./figures/install_anaconda_open_base_environment_terminal.png + :width: 500 + :alt: Opening the terminal for the ``mhkit`` environment + + +Using Miniconda: + +- Launch your preferred terminal and execute the following command: + +.. code-block:: bash + + conda activate base + +3. Download the most recent `MHKiT-Python conda environment file (environment.yml) `_ + +- Using the terminal + + - Execute the following command: + + .. code-block:: bash + + curl -o mhkit_environment.yml https://raw.githubusercontent.com/MHKiT-Software/MHKiT-Python/master/environment.yml + +- Downloading the file manually. + + + - Navigate to the `MHKiT-Python conda environment file (environment.yml) `_ and download using the "download" button (screenshot below). Move the downloaded file to the current folder in your terminal and rename the file to ``mhkit_environment.yml`` + +.. image:: ./figures/install_mhkit_python_env_yaml_download.png + :width: 500 + :alt: Download MHKiT-Python environment.yml from GitHub + +3. Download the most recent `MHKiT-Python conda environment file (environment.yml) `_ + +- Using the terminal + + - Execute the following command: + + .. code-block:: bash + + curl -o mhkit_environment.yml https://raw.githubusercontent.com/MHKiT-Software/MHKiT-Python/master/environment.yml + +- Downloading the file manually + + - Navigate to the `MHKiT-Python conda environment file (environment.yml) `_ and use the "download" button to save the file to your local machine. Move the downloaded file to the directory where your terminal is currently open and rename it to ``mhkit_environment.yml``. + + .. image:: ./figures/install_mhkit_python_env_yaml_download.png + :width: 500 + :alt: Download MHKiT-Python environment.yml from GitHub -Using this option to install MHKiT-Python will require following the `Pecos installation instructions `_ to install the Pecos package dependency. + +4. Create a new environment using the downloaded environment file. In the terminal execute the following command: + + .. code-block:: bash + + conda env create --name -f mhkit_environment.yml + + Replacing ```` with the desired name for your environment. Common convention is to call the MHKiT-Python environment ``mhkit``. + +5. Install MHKiT-Python in the new environment. In the terminal execute the following commands: + + .. code-block:: bash + + conda activate + + .. code-block:: bash + + conda install -c conda-forge mhkit + + - To run the `MHKiT-Python example notebooks `_ please install the following additional dependencies: + + .. code-block:: bash + + pip install jupyter notebook folium utm + + +To verify your MHKiT-Python installation navigate to the `Verifying MHKiT-Python installation <#verifying-mhkit-python-installation>`_ section. .. Note:: - If you plan to contribute to the MHKiT-Python open-source software, please `fork `_ the MHKiT-Python repository into your GitHub user account. - Install MHKiT using Option 2 above. - To include your additions to the MHKiT-Python code, please submit a `pull request `_ to the MHKiT-Python develop branch. - Once reviewed by the MHKiT-Python development team, pull requests will be merged into MHKiT-Python and included in future releases. + To use MHKiT-Python in a new terminal activate the environment first by executing:: + + conda activate + + With the anaconda environment activated your terminal prompt should show the environment name in parentheses, indicating that the environment is active. For example, it might look like:: + (env_name) user@machine:~$ -Test MHKiT-Python installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To test that MHKiT-Python is installed correctly, open a Python console and run:: +Option 2: PIP Install from Python +""""""""""""""""""""""""""""""""" + +To install MHKiT-Python using `pip `_:: + + pip install mhkit + +.. Note:: + The if the ``pip`` installation fails please try the installing MHKiT-Python with Anaconda + +Option 3: Clone Repository from GitHub +"""""""""""""""""""""""""""""""""""""" + +This option is recommended for MHKiT-Python developers. To install MHKiT-Python using `git `_:: + + git clone https://github.com/MHKiT-Software/MHKiT-Python + cd mhkit-python + pip install -e . + +Using this option to install MHKiT-Python will require following the `Pecos installation instructions `_ to install the Pecos package dependency. + +.. Note:: + If you plan to contribute to the MHKiT-Python open-source software, please `fork `_ the MHKiT-Python repository into your GitHub user account. + Install MHKiT using Option 2 above. + To include your additions to the MHKiT-Python code, please submit a `pull request `_ to the MHKiT-Python develop branch. + Once reviewed by the MHKiT-Python development team, pull requests will be merged into MHKiT-Python and included in future releases. + +Verifying MHKiT-Python installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To verify that MHKiT-Python is installed correctly, open a Python console and run:: import mhkit -If MHKiT-Python is installed properly, Python proceeds to the next line and no other output is printed to the screen. -If MHKiT-Python is not installed properly, the user will see the following error:: +If MHKiT-Python is installed properly, Python proceeds to the next line and no other output is printed to the screen. If MHKiT-Python is not installed properly, the user will see the following error:: ImportError: No module named mhkit @@ -75,6 +185,5 @@ To test a simple function using MHKiT-Python, the user can compute the equivalen The results should be:: - ED = 30 - AP = 706.8583470577034 - + ED = 30 + AP = 706.8583470577034 diff --git a/docs/source/overview.rst b/docs/source/overview.rst index cecd12e..29d752f 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -95,9 +95,10 @@ Developers should run software tests locally before submitting a pull request, u A summary pdf will be created after running the tests summarizing the test results. -MHKiT-Python tests using the Python package nose:: +MHKiT-Python tests using the Python package pytest:: - nosetests -v --with-coverage --cover-package=mhkit mhkit + pip install -r requirements-dev.txt + pytest MHKiT-MATLAB tests using the MATLAB API::