From 5d0679e67ba547e27d045bc04eb13ed06be69594 Mon Sep 17 00:00:00 2001 From: Asher Merrill Date: Fri, 15 May 2026 15:08:43 -0700 Subject: [PATCH] docs: add install/environment docs --- INSTALL.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..c50d722 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,111 @@ +# UncertainSCI Python Environment +I couldn't find complete environment installation instructions, so I went ahead and created my own. + +**Python Versions:** UncertainSCI officially supports Python versions 3.9 to 3.11. Newer Python may incidentally work, but at this time its support has not been tested. The team is in the midst of the discussion of providing formal support for newer Python. + +## Dependency Overview +This is an overview of the dependencies for various purposes for UncertainSCI. + +### Base Dependencies +At a minimum, UncertainSCI requires all packages in the project's requirements.txt. + +### Doc Dependencies +To build the docs, UncertainSCI requires +- pandoc +- sphinx +- sphinxcontrib-bibtex +- sphinx-markdown-tables +- nbsphinx +- recommonmark + +### Testing & Linting Dependencies +To test and lint the codebase, UncertainSCI requires +- flake8 +- pytest +- pytest-cov + +### Nice-to-haves +- ipython +- jupyter + +## Environment for Production +It is assumed your production environment does not need docs (e.g., pandoc), testing nor linting (e.g., flake8 nor pytest), nor interactive interfaces (e.g., jupyter). The packages and tools for these features are therefore omitted from these installation instructions. + +### With conda +1. Change to the repository root. +2. Set the `ENVNAME` and `PYVER` variables. On *NIX, + ```shell + export ENVNAME= + export PYVER= + ``` + On Windows, + ```shell + $ENVNAME="" + $PYVER="" + ``` +3. Create and activate the conda environment, then install UncertainSCI, + ```shell + conda create -n $ENVNAME python=$PYVER pandoc + conda activate $ENVNAME + python -m pip install . + ``` + +### Without conda +1. You have already installed the version of Python with which you wish to run UncertainSCI. +2. Change to the repository root. +3. Create and activate a virtual environment inside of which to run UncertainSCI, + ```shell + python -m venv .venv + ``` + Activate the virtual environment according to your system. +4. Install UncertainSCI, + ```shell + python -m pip install . + ``` + +## Environment for Development +It is assumed to develop UncertainSCI that you want to be able to build the docs, test and flake the codebase, and have reasonably modern interactive tools. + +### With conda +1. Change to the repository root. +2. Set the `ENVNAME` and `PYVER` variables. On *NIX, + ```shell + export ENVNAME= + export PYVER= + ``` + On Windows, + ```shell + $ENVNAME="" + $PYVER="" + ``` +3. Create and activate the conda environment, then install UncertainSCI, + ```shell + conda create -n $ENVNAME python=$PYVER pandoc + conda activate $ENVNAME + python -m pip install . + ``` +4. Install development helpers, + ```shell + python -m pip install pandoc sphinx sphinxcontrib-bibtex sphinx-markdown-tables nbsphinx recommonmark # docs + python -m pip install flake8 pytest pytest-cov # linting and testing + python -m pip install ipython jupyter # nice-to-haves + ``` + +### Without conda +1. You have already installed the version of Python with which you wish to run UncertainSCI. +2. Change to the repository root. +3. Create and activate a virtual environment inside of which to run UncertainSCI, + ```shell + python -m venv .venv + ``` + Activate the virtual environment according to your system. +4. Install UncertainSCI, + ```shell + python -m pip install . + ``` +5. Install development helpers, + ```shell + python -m pip install pandoc sphinx sphinxcontrib-bibtex sphinx-markdown-tables nbsphinx recommonmark # docs + python -m pip install flake8 pytest pytest-cov # linting and testing + python -m pip install ipython jupyter # nice-to-haves + ```