Document incompatibility with python 3.14

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 <env_name> python=3.12
+    conda create -n <env_name> python=3.13
     conda activate <env_name>
-    pip install jwst
+    pip install jwst==1.19.1
 
-You can also install a specific version:
-
-    conda create -n <env_name> python=3.12
-    conda activate <env_name>
-    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 <env_name> python=3.12
+    conda create -n <env_name> python=3.13
     conda activate <env_name>
     pip install git+https://github.com/spacetelescope/jwst
 

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 <env_name> python=3.13\n"
+            "conda activate <env_name>\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()

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 <env_name> python=3.12
-    conda activate <env_name>
-    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 <env_name> python=3.12
     conda activate <env_name>
-    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 <env_name> python=3.12
+    conda create -n <env_name> python=3.13
     conda activate <env_name>
     pip install git+https://github.com/spacetelescope/jwst
 

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