Merge pull request #899 from mperrin/docs_improvements_v131

Docs improvements, including for matching PSFs to data
spacetelescope · Sep 11, 2024 · b45d82d · b45d82d
2 parents 1c915ce + d37fb3d
commit b45d82d
Show file tree

Hide file tree

Showing 14 changed files with 1,978 additions and 872 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -83,17 +83,18 @@
     "numpydoc",
 ]
 
+
+if on_rtd:
+    extensions.append('sphinx.ext.mathjax')
+
 numpydoc_show_class_members = False
 
 autosummary_generate = True
 graphviz_dot = "dot"
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
+# The suffix of source filenames.
 source_suffix = ".rst"
 
 # The master toctree document.
@@ -118,26 +119,53 @@
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+pygments_style = "default"
 
-intersphinx_mapping.update(  # noqa - defined in star import
-    {
-        "poppy": ("http://poppy-optics.readthedocs.io/", None),
-    }
-)
+#intersphinx_mapping.update(  # noqa - defined in star import
+#    {
+#        "poppy": ("http://poppy-optics.readthedocs.io/", None),
+#    }
+#)
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "stsci_rtd_theme"
-html_theme_path = [stsci_rtd_theme.get_html_theme_path()]
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    "collapse_navigation": True,
+    "sticky_navigation": False,
+    # "nosidebar": "false",
+    # "sidebarbgcolor": "#4db8ff",
+    # "sidebartextcolor": "black",
+    # "sidebarlinkcolor": "black",
+    # "headbgcolor": "white",
+}
+
+html_logo = '_static/stsci_pri_combo_mark_white.png'
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+# html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

diff --git a/docs/index.rst b/docs/index.rst
@@ -24,7 +24,7 @@ WebbPSF has been developed by Marshall Perrin, Marcio Meléndez, Shannon Osborne
 Getting Started with WebbPSF
 ----------------------------
 
-See :ref:`using_api`.
+See `Using WebbPSF <usage.html>`_.
 
 .. admonition:: Quickstart Jupyter Notebook
 
@@ -48,8 +48,8 @@ Contents
    intro.rst
    installation.rst
    relnotes.rst
-   usage.rst
-   psf_grids.rst
+   usage.ipynb
+   psf_grids.ipynb
 
 .. toctree::
    :maxdepth: 1

diff --git a/docs/intro.rst b/docs/intro.rst
@@ -98,7 +98,7 @@ Types of Fourier Transform Calculation in WebbPSF
   * NIRISS NRM, GR799XD: Matrix DFT
   * NIRSpec and NIRISS slit spectroscopy: FFT and Matrix DFT
 
-See :ref:`Optimizing Performance and Parallelization <performance_and_parallelization>` in the POPPY documentation for more details on calculation performance.
+See `Performance and Parallelization <https://poppy-optics.readthedocs.io/en/latest/performance.html>`_ in the POPPY documentation for more details on calculation performance.
 
 Getting WebbPSF
 ---------------

diff --git a/docs/jwst_matching_psfs_to_data.ipynb b/docs/jwst_matching_psfs_to_data.ipynb
diff --git a/docs/psf_grids.ipynb b/docs/psf_grids.ipynb
diff --git a/docs/psf_grids.rst b/docs/psf_grids.rst
diff --git a/docs/references.rst b/docs/references.rst
@@ -28,7 +28,7 @@ of the measured distortions within the instruments.
 
 WebbPSF does not include any absolute throughput information for any SIs, only
 the relative weighting for different wavelengths in a broadband calculation.
-See :ref:`the note on PSF normalization <normalization>` for further
+See `the docs on PSF normalization <usage.html#Customizing-PSF-Calculations:-PSF-Normalizations-and-Flux-Calibrations>_` for further
 discussion.
 
 

diff --git a/docs/release.rst b/docs/release.rst
@@ -63,30 +63,6 @@ When you are ready, proceed with the WebbPSF release as follows:
 
  #. Release to PyPI. This should now happen automatically on GitHub Actions. This will be triggered by a GitHub Actions build of a tagged commit on the `stable` branch, so it will happen automatically on the prior step for the PR into `stable`.
 
-.. note::
-
-  Once conda installation is working again, find this page in the documentation
-  for version 1.0.0 and adapt the steps from the "Releasing a new version
-  through AstroConda" section to the new process.
-
-Releasing a new version through AstroConda
-==========================================
-
-To test that an Astroconda package builds, you will need ``conda-build``::
-
-   $ conda install conda-build
-
-#. Fork (if needed) and clone https://github.com/astroconda/astroconda-contrib
-#. If there is a new version of POPPY available to package, edit `poppy/meta.yaml <https://github.com/astroconda/astroconda-contrib/blob/master/poppy/meta.yaml>`_ to reflect the new ``version`` and ``git_tag``.
-#. If the minimum needed version of the webbpsf-data package has changed in ``webbpsf/__init__.py``, edit `webbpsf-data/meta.yaml <https://github.com/astroconda/astroconda-contrib/blob/master/webbpsf-data/meta.yaml>`_ to reflect the new ``version`` and ``url``.
-#. Edit `webbpsf/meta.yaml <https://github.com/astroconda/astroconda-contrib/blob/master/webbpsf/meta.yaml>`_ to reflect the new versions of POPPY and webbpsf-data, if necessary.
-#. Edit in the ``git_tag`` name from ``git tag`` in the PyPI release instructions (``v0.X.Y``).
-#. Verify that you can build the package from the astroconda-contrib directory: ``conda build -c http://ssb.stsci.edu/astroconda webbpsf``
-#. Commit your changes to a new branch and push to GitHub.
-#. Create a pull request against ``astroconda/astroconda-contrib``.
-#. Wait for SSB to build the conda packages.
-#. (optional) Create a new conda environment to test the package installation following :ref:`these instructions <install-with-conda>`.
-
 
 Finishing the release
 =====================

diff --git a/docs/relnotes.rst b/docs/relnotes.rst
@@ -14,11 +14,7 @@ See https://github.com/spacetelescope/webbpsf/issues for currently open issues a
   the pupil entrance aperture in the discrete Fourier transform. If you need
   accurate PSF information at such large radii, please contact Marshall Perrin
   or Marcio Melendez for higher resolution pupil data.
-
-**The following factors are NOT included in these simulations:**
-
 * Coronagraphic masks are assumed to be perfect (i.e. the masks exactly match their design parameters.)
-* Most detector effects, such as intrapixel sensitivity variations or interpixel capacitance. There are currently no plans to include these WebbPSF itself.  Generate a subsampled PSF and use a separate detector model code instead. The one exception is a scattering artifact in the MIRI imager detector substrate.
 
 ------------------
 
@@ -356,7 +352,7 @@ Note, when upgrading to this version you will need to update to the latest data
 
 **WFIRST Improvements**
 
-- *The WFI optical model has been updated to use optical data from the Cycle 8 design revision.* These include updated Zernike coefficients for field-dependent wavefront error, and masked and unmasked pupil images for each SCA, and updated filter throughputs (consistent with values used in Pandeia 1.4.2). The correct pupil file will automatically be selected for each calculation based on the chosen detector position and filter.   The pupil files are consistent with those provided in the WFI cycle 8 reference information, but have been resampled onto a common pixel scale.  See :ref:`WFIRST instrument model details <wfirst_wfi>` for more.  [:pr:`309` :user:`robelgeda`]
+- *The WFI optical model has been updated to use optical data from the Cycle 8 design revision.* These include updated Zernike coefficients for field-dependent wavefront error, and masked and unmasked pupil images for each SCA, and updated filter throughputs (consistent with values used in Pandeia 1.4.2). The correct pupil file will automatically be selected for each calculation based on the chosen detector position and filter.   The pupil files are consistent with those provided in the WFI cycle 8 reference information, but have been resampled onto a common pixel scale.  See `WFIRST instrument model details <roman.html>`_ for more.  [:pr:`309` :user:`robelgeda`]
 - Note, WFI's filters have been renamed so they all begin with “F”; `see the table here <https://github.com/spacetelescope/webbpsf/pull/309>`_ .
 - *The WFI wavelength range has now been extended to cover the 0.48 - 2.0 µm range.* [:pr:`309` :user:`robelgeda`]
 - *Expanded ``psf_grid`` method’s functionality so it can also be used to make grids of WFIRST PSFs.* Note that focal plane distortion is not yet implemented for WFIRST PSFs and so ``add_distortion`` keyword should not be used for this case. [:pr:`294`, :user:`shanosborne`]
@@ -872,7 +868,7 @@ directory.
   and the developers of the `Astropy affiliated package template <https://github.com/astropy/package-template>`_.
   Thanks in particular to Christine Slocum for integration into the STScI SSB software distribution.
 
-* Improvements to parallelization code. Better :ref:`documentation for parallelization <performance_and_parallelization>`.  PyFFTW3 replaced with pyFFTW for optimized
+* Improvements to parallelization code. Better documentation for parallelization.  PyFFTW3 replaced with pyFFTW for optimized
   FFTs (yes, those are two entirely different packages).
 
 * Alternate GUI using the wxpython widget toolkit in place of the older/less

diff --git a/docs/roman.rst b/docs/roman.rst
@@ -25,7 +25,7 @@ To work with the WFI model, import and instantiate it just like any of the JWST
     >>> from webbpsf import roman
     >>> wfi = roman.WFI()
 
-Usage of the WFI model class is, for the most part, just like any other WebbPSF instrument model. For help setting attributes like filters, position offsets, and sampling, refer to :ref:`using_api`.
+Usage of the WFI model class is, for the most part, just like any other WebbPSF instrument model. For help setting attributes like filters, position offsets, and sampling, refer to `Using WebbPSF <usage.html>`_.
 
 The WFI model includes a model for field dependent PSF aberrations. With as large a field of view as the WFI is designed to cover, there will be variation in the PSF from one end of the field of view to the other. WebbPSF's WFI model faithfully reproduces the field dependent aberrations calculated from the Goddard Roman team's Cycle 9 WFI design. This provides a toolkit for users to assess the impact of inter-SCA and intra-SCA PSF variations on science cases of interest.
 

diff --git a/docs/usage.ipynb b/docs/usage.ipynb