diff --git a/README.md b/README.md index 1b81cf0b9e..d2c70808ef 100644 --- a/README.md +++ b/README.md @@ -8,28 +8,30 @@ [![Powered by STScI Badge](https://img.shields.io/badge/powered%20by-STScI-blue.svg?colorA=707170&colorB=3e8ddd&style=flat)](https://www.stsci.edu) [![Powered by Astropy Badge](https://img.shields.io/badge/powered%20by-AstroPy-orange.svg?style=flat)](https://www.astropy.org/) [![DOI](https://zenodo.org/badge/60551519.svg)](https://zenodo.org/badge/latestdoi/60551519) +[![Python Versions](https://img.shields.io/pypi/pyversions/jwst)](https://pypi.org/project/jwst/) ![STScI Logo](docs/_static/stsci_logo.png) -> [!IMPORTANT] -> JWST requires a C compiler for dependencies. - -> [!NOTE] -> Linux and MacOS platforms are tested and supported. Windows is not currently supported. - > [!WARNING] +> `jwst` is not yet compatible with python 3.14. +> > Installation of `jwst` versions `1.15.1` through `1.16.1` will pull an incompatible version of the `gwcs` dependency - > this can be remedied by downgrading the gwcs version through e.g. `pip install 'gwcs<0.22'` > > Installation on MacOS Mojave 10.14 will fail due to lack of a stable build for dependency ``opencv-python``. +> [!IMPORTANT] +> JWST requires a C compiler for dependencies. +> +> Linux and MacOS platforms are tested and supported. Windows is not currently supported. + ## Installation Please contact the [JWST Help Desk](https://jwsthelp.stsci.edu) for installation issues. The easiest way to install the latest `jwst` release into a fresh virtualenv or conda environment is - pip install jwst + pip install jwst==1.19.1 ### Detailed Installation @@ -56,22 +58,22 @@ Remember that all conda operations must be done from within a bash/zsh shell. You can install the latest released version via `pip`. From a bash/zsh shell: - conda create -n python=3.12 + conda create -n python=3.13 conda activate - pip install jwst + pip install jwst==1.19.1 -You can also install a specific version: - - conda create -n python=3.12 - conda activate - pip install jwst==1.18.1 +If no version tag is specified in the install command, `pip` will find the latest release compatible +with the current environment. This can lead to an unintended `jwst` version, if the latest release +of `jwst` is not compatible with your environment's python version. Explicitly setting the version +in the install command will return an informative error if the latest release is not compatible +with your environment. ### Installing the development version from Github You can install the latest development version (not as well tested) from the Github main branch: - conda create -n python=3.12 + conda create -n python=3.13 conda activate pip install git+https://github.com/spacetelescope/jwst diff --git a/docs/conf.py b/docs/conf.py index 3b211c773a..b90d186c4f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,6 +22,10 @@ from stpipe import Step from sphinx.ext.autodoc import AttributeDocumenter +from sphinx.util.docutils import SphinxDirective +from docutils import nodes + +from jwst import __version__ as version class StepSpecDocumenter(AttributeDocumenter): @@ -47,9 +51,31 @@ def add_content(self, more_content): self.add_line(f" {txt}", source_name, 2) +class PipInstallVersionDirective(SphinxDirective): + + def run(self): + help_text = f"pip install jwst=={version}\n" + paragraph_node = nodes.literal_block(text=help_text) + return [paragraph_node] + + +class CondaInstallVersionDirective(SphinxDirective): + + def run(self): + help_text = ( + "conda create -n python=3.13\n" + "conda activate \n" + f"pip install jwst=={version}\n" + ) + paragraph_node = nodes.literal_block(text=help_text) + return [paragraph_node] + + def setup(app): # add a custom AttributeDocumenter subclass to handle Step.spec formatting app.add_autodocumenter(StepSpecDocumenter, True) + app.add_directive('pip_install_literal', PipInstallVersionDirective) + app.add_directive('conda_install_literal', CondaInstallVersionDirective) conf = ConfigParser() diff --git a/docs/getting_started/install.rst b/docs/getting_started/install.rst index eb03f772ce..bd5e0d5e34 100644 --- a/docs/getting_started/install.rst +++ b/docs/getting_started/install.rst @@ -39,28 +39,34 @@ shell. .. warning:: JWST requires a C compiler for dependencies. + JWST is only compatible with python versions 3.11, 3.12, and 3.13. + .. warning:: Installation on MacOS Mojave 10.14 will fail due to lack of a stable build for dependency ``opencv-python``. Installing Latest Release ------------------------- -You can install the latest released version via ``pip``. From a bash/zsh shell:: +You can install the latest released version via ``pip``. From a bash/zsh shell: - conda create -n python=3.12 - conda activate - pip install jwst +.. conda_install_literal:: + +If no version tag is specified in the install command, ``pip`` will find the latest release compatible +with the current environment. This can lead to an unintended ``jwst`` version, if the latest release +of ``jwst`` is not compatible with your environment's python version. Explicitly setting the version +in the install command will return an informative error if the latest release is not compatible +with your environment. .. _installing_previous_release: Installing Previous Releases ---------------------------- -You can also install a specific version (from ``jwst 0.17.0`` onward):: +You can also install a specific version:: conda create -n python=3.12 conda activate - pip install jwst==1.12.5 + pip install jwst==1.17.1 .. _installing_dev: @@ -70,7 +76,7 @@ Installing the Development Version from Github You can install the latest development version (not as well tested) from the Github main branch:: - conda create -n python=3.12 + conda create -n python=3.13 conda activate pip install git+https://github.com/spacetelescope/jwst diff --git a/docs/getting_started/quickstart.rst b/docs/getting_started/quickstart.rst index 9c6848f3b0..92b1d777aa 100644 --- a/docs/getting_started/quickstart.rst +++ b/docs/getting_started/quickstart.rst @@ -29,7 +29,7 @@ If you don't already have ``conda``, please follow the To create a conda environment specifically for the latest stable release of ``jwst`` (in this example, called jwst_latest):: - conda create --name jwst_latest python=3.12 + conda create --name jwst_latest python=3.13 This will create a new, (nearly) empty Python 3.12 environment in which you can install the ``jwst`` package. @@ -41,9 +41,9 @@ Once you have created your conda environment, make sure it is active by doing:: conda activate jwst_latest To install the last stable release of ``jwst``, and all its basic dependencies -(e.g., numpy, stcal):: +(e.g., numpy, stcal): - pip install jwst +.. pip_install_literal:: For detailed installation instructions, including how to install the development version of ``jwst`` from Github or how to install a previous released version, see