diff --git a/docs/install.rst b/docs/install.rst index e828bac88..2559d139a 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,66 +1,36 @@ Installation ============ -GeoCAT-examples is a collection of standalone visualization examples, and it is not distributed -as a conda package; thus, there is no installation for it (via conda or other package management systems). -The easiest way to access GeoCAT-examples scripts as a whole is by cloning the repo and then configuring -`Conda `_ environment to run them in. +GeoCAT-examples is a collection of standalone visualization examples (not distributed +as a package on PyPI or conda-forge). -This guide includes only the instructions to run GeoCAT-examples scripts locally. For information about installing the -entire GeoCAT project, see our -`Contributor's Guide <(https://geocat.ucar.edu/pages/contributing.html)>`_. +The easiest way to run multiple GeoCAT-examples scripts is to clone the GeoCAT-examples +repository. Then configure a `Conda `_ environment to run them in +as described below in `Creating a Conda environment`_. + +To run individual GeoCAT-examples, you can also download the examples as scripts or Jupyter +notebooks by clicking the download buttons at the bottom of each example in the gallery. To set up +an environment in which to run the examples either ensure you have the packages mentioned +in the import packages section at the top of the script installed or install the full GeoCAT-examples +environment as described in `Creating a Conda environment`_. Creating a Conda environment ---------------------------- -This repository provides a Conda environment file that can be used to create an evironment to build -both (1) and (2). However, each of Jupyter notebooks under (2) will require their own additional -dependencies that are written in the beginning of them and needs to be installed into the active -Conda environment. Furthermore, users with advanced Conda knowledge will see that the Conda environment -file provided in this repo contains much more dependencies than the base Conda environment reuqires (i.e. -essentially a Jupyter technology such as Jupyter Lab to execute notebooks) to build (2). +This repository provides a `Conda environment file `_ +that can be used to create an evironment to run the examples included in this gallery. -In order to create a Conda environment using the file provided by this repo, from the root directory of -the cloned geocat-examples directory, run the following commands:: +To create a Conda environment using the file provided by this repo, from the root directory of +the cloned geocat-examples repository (or the directory containing the ``conda_environment.yml`` +file you downloaded), run the following commands:: conda env create -f conda_environment.yml -n geocat-examples conda activate geocat-examples -Note that the Conda package manager automatically installs all the `required` +Note that the Conda package manager automatically installs all of the `required` dependencies of GeoCAT-examples listed under ``conda_environment.yml`` file (such as ``geocat-comp``, -``geocat-datafiles``, ``cartopy``, ``matplotlib``, ``netcdf4``, etc.); therefore, there is no need for -explicitly installing those packages. - -If you need to make use of other software packages with GeoCAT-examples or are interested in -running the Jupyter notebooks under (2) mentioned above, you may need to install them into your -``geocat-examples`` environment at anytime with a command as in the -following example (assuming your ``geocat-examples`` environment is already activated):: - - conda install -c bokeh bokeh - -or in the way that is suggested by each Jupyter notebook under (2). - - -Updating the ``geocat-examples`` environment --------------------------------------------- -It is important to keep your environment up to date so you get the latest bugfixes and changes. -This can be done as follows: - -Make sure your Conda is up to date by running this command from the terminal:: - - conda update conda - -Activate the conda environment you want to update:: - - conda activate geocat-examples - -Update all packages in the environment:: - - conda update --all - -Note that this will update all packages to the most recent version that is compatible with the other packages in the -environment. You may notice with ``conda list`` that not every package in your environment is the latest version. -This is generally okay. +``geocat-datafiles``, ``cartopy``, ``matplotlib``, ``netcdf4``, etc.). There is no need to +explicitly install these packages. If you are interested in learning more about how Conda environments work, please visit the `managing environments `_