diff --git a/.readthedocs.yaml b/.readthedocs.yaml deleted file mode 100644 index 7784ce3..0000000 --- a/.readthedocs.yaml +++ /dev/null @@ -1,37 +0,0 @@ -# Read the Docs configuration file for MkDocs projects -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - -# Required -version: 2 - -# Set the version of Python and other tools you might need -build: - os: ubuntu-22.04 - tools: - python: "3.12" - jobs: - # https://docs.readthedocs.io/en/stable/build-customization.html#support-git-lfs-large-file-storage - post_checkout: - # Download and uncompress the binary - # https://git-lfs.github.com/ - - wget - https://github.com/git-lfs/git-lfs/releases/download/v3.1.4/git-lfs-linux-amd64-v3.1.4.tar.gz - - tar xvfz git-lfs-linux-amd64-v3.1.4.tar.gz - # Modify LFS config paths to point where git-lfs binary was downloaded - - git config filter.lfs.process "`pwd`/git-lfs filter-process" - - git config filter.lfs.smudge "`pwd`/git-lfs smudge -- %f" - - git config filter.lfs.clean "`pwd`/git-lfs clean -- %f" - # Make LFS available in current repository - - ./git-lfs install - # Download content from remote - - ./git-lfs fetch - # Make local files to have the real content on them - - ./git-lfs checkout - -mkdocs: - configuration: mkdocs.yml - -# Optionally declare the Python requirements required to build your docs -python: - install: - - requirements: docs/requirements.txt diff --git a/README.md b/README.md index 9d5c0c1..fa80014 100644 --- a/README.md +++ b/README.md @@ -34,9 +34,20 @@ analysis and visualization capabilities without requiring a steep learning curve as well as the E3SM land model ELM's input and output files on `ne*np4` and `ne*pg2` grids. -## Getting Started +## Installation -See our [documentation page](https://kitware.github.io/QuickView/guides/quickview/getting_started.html). +QuickView supports local installation through desktop bundles or conda, as well as +remote usage. See the [system requirements](https://kitware.github.io/QuickView/guides/system_requirements.html) +and [installation instructions](https://kitware.github.io/QuickView/guides/install_and_launch.html). + +## Runtime dependencies + +QuickView's runtime dependencies are listed under `requirements.run` in the +[conda-forge feedstock recipe](https://github.com/conda-forge/e3sm-quickview-feedstock/blob/main/recipe/recipe.yaml#L28). + +## User's Guide + +See [documentation page](https://kitware.github.io/QuickView/guides/quickview/getting_started.html). ## Project Background diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 5c14505..cde521b 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -54,6 +54,7 @@ export default defineConfig({ { text: "Connecitiviy Files", link: "/guides/connectivity" }, { text: "Simulation Files", link: "/guides/simulation_data" }, { text: "Install and Launch", link: "/guides/install_and_launch" }, + { text: "System Requirements", link: "/guides/system_requirements" }, ], }, { diff --git a/docs/guides/install_and_launch.md b/docs/guides/install_and_launch.md index 4531918..dc9e6c0 100644 --- a/docs/guides/install_and_launch.md +++ b/docs/guides/install_and_launch.md @@ -1,6 +1,9 @@ # Install and launch -All tools of the **QuickView** family are available as +(See [System Requirements](/guides/system_requirements.md) for the prerequisites +for local installation and remote usage.) + +Tools of the QuickView family are available as **Conda** and **PyPI** packages as well as **pre-compiled desktop bundles** for various OS's including Mac, Windows, and Linux. The table below summarizes where the different packages @@ -56,9 +59,8 @@ For example, to create a conda environment named `quickview-env` then install QuickView and QuickCompare, we can use the following commands: ```sh -conda create --name quickview-env python=3.13 +conda create --name quickview-env -c conda-forge python=3.13 typing_extensions conda activate quickview-env -pip install typing_extensions conda install conda-forge::e3sm-quickview conda install conda-forge::e3sm_compareview ``` diff --git a/docs/guides/system_requirements.md b/docs/guides/system_requirements.md new file mode 100644 index 0000000..957aeb0 --- /dev/null +++ b/docs/guides/system_requirements.md @@ -0,0 +1,50 @@ +# System Requirements + +This page describes the prerequisites for **local installation** and **remote usage** +of tools in the QuickView family. See [Install and Launch](/guides/install_and_launch.md) +for available packages, desktop bundles, and installation instructions. + +## Local installation using a desktop bundle + +Requirements: + +- A desktop bundle for the selected tool matching the operating system and processor architecture. +- Sufficient disk space and permission to install and run the application. +- Access to [simulation files](/guides/simulation_data.md) and [connectivity files](/guides/connectivity.md). + +The bundle includes the application's runtime dependencies (e.g., Python, ParaView, VTK). +No separate installation of these dependencies or a package manager is required. + +On macOS, unsigned bundles require the +[quarantine-removal step](/guides/install_and_launch.md#desktop-bundles). +On Linux, additional system libraries may be required, depending on the distribution. + +## Local installation using conda + +Requirements: + +- A working conda installation, such as Miniconda or Anaconda. +- Internet access to download packages. +- Sufficient disk space and write permission for the conda environment and package cache. +- A web browser. +- Access to [simulation files](/guides/simulation_data.md) and [connectivity files](/guides/connectivity.md). + +Conda installs Python and the selected tool's declared dependencies. + +## Remote usage + +The local computer requires: + +- A web browser. +- Network access to the remote system. +- For connections through an SSH tunnel, an SSH client that supports port forwarding. + +The remote system requires a working installation of the selected tool and access to +[simulation files](/guides/simulation_data.md) and [connectivity files](/guides/connectivity.md). +An account and permission to run the application on an appropriate node are also required. +For system-specific instructions, see, for example, the +[NERSC launching guide](/hpcsystems/nersc/launching.md) and the +[Chrysalis guide](/hpcsystems/chrysalis/chrysalis.md). + +No local installation of the selected tool or its runtime dependencies +(e.g., Python, ParaView, VTK) is required.