Merge pull request #53 from AstarVienna/fh/rtdtheme

Documentation changes before release

docs/source/GettingStarted.rst

@@ -14,12 +14,19 @@ and then call the :meth:`.get_sky_spectrum()` method to get a default data set
 from the ESO SkyCalc server::
 
     >>> tbl = skycalc.get_sky_spectrum()
-    >>> print(tbl[:2])
-     lam         trans                 flux
-      um                      ph / (arcsec2 m2 s um)
-    ----- ------------------- ----------------------
-      0.3 0.03407993552308744     14.237968836733746
-    0.301 0.04638097547092783     19.640944348240403
+    >>> print(tbl[:5])
+     lam    trans           flux         
+      nm      1    ph / (s um arcsec2 m2)
+    ------ ------- ----------------------
+    300.00 0.03408                 13.145
+    300.30 0.03638                 13.233
+    300.60 0.03900                 15.765
+    300.90 0.04412                 17.626
+    301.20 0.05093                 22.844
+
+.. versionchanged:: v0.2.0
+
+   The `lam` column is now in nm, following the change by the ESO server.
 
 If we were to plot up the columns ``trans`` and ``flux`` against ``lam`` we
 would have something like this:
@@ -31,16 +38,15 @@ would have something like this:
 
     tbl = SkyCalc().get_sky_spectrum()
 
-    plt.figure(figsize=(8,8))
-    plt.subplot(211)
-    plt.plot(tbl["lam"], tbl["trans"])
-    plt.xlabel("Wavelength [um]")
-    plt.ylabel("Transmission")
-    plt.subplot(212)
-    plt.plot(tbl["lam"], tbl["flux"])
-    plt.xlabel("Wavelength [um]")
-    plt.ylabel("Emission [ph s-1 m-2 um-1 arcsec-2]")
-    plt.semilogy()
+    fig, ax = plt.subplots(2, 1, sharex=True, figsize=(8,8))
+    fig.subplots_adjust(hspace=0)
+    ax[0].plot(tbl["lam"], tbl["trans"], lw=1)
+    ax[1].semilogy(tbl["lam"], tbl["flux"], lw=1)
+    ax[0].set_ylabel("Transmission")
+    ax[1].set_ylabel(f"Emission [{tbl['flux'].unit}]")
+    ax[1].set_xlabel(f"Wavelength [{tbl['lam'].unit}]")
+    ax[0].grid(True, ls=":")
+    ax[1].grid(True, ls=":")
 
 
 Returned FITS file
@@ -62,6 +68,10 @@ including::
     >>> tbl = skycalc.get_sky_spectrum(return_type="synphot")
     >>> tbl = skycalc.get_sky_spectrum(return_type="tab-ext")
 
+.. note::
+    :class: margin
+
+    The ``synphot`` output format requires installing `skycalc_ipy` with the `synphot` extra, unless ``synphot`` is already installed in the system anyway.
 
 ============== ======== ========
 Value          Shortcut Returned
@@ -143,6 +153,15 @@ based on the recorded atmospheric conditions using the ESO Almanac service::
      'ecl_lat': -28.6776,
      'observatory': 'paranal'}
 
+.. warning:: The Almanac currently returns `msolflux=-1` for dates after 2023-04-30.
+    :class: margin
+
+    This indicates an error on the Almanac side. The only way to deal with this
+    (without being super hacky) is for the user to reset the average solar flux
+    to something normal before proceeding::
+
+        >>> skycalc["msolflux"] = 130       # sfu
+
 By default the returned values **DO NOT** overwrite the current ``skycalc``
 values. This is to give us the chance to review the data before adding it to
 our :class:`SkyCalc` query. If we already know that we want these values,
@@ -154,14 +173,6 @@ we can set the ``update_values`` flag to ``True``::
     >>> skycalc["airmass"]
     1.07729
 
-.. warning:: The Almanac currently returns `msolflux=-1` for dates after 2019-01-31.
-
-    This indicates an error on the Almanac side. The only way to deal with this
-    (without being super hacky) is for the user to reset the average solar flux
-    to something normal before proceeding::
-
-        >>> skycalc["msolflux"] = 130       # sfu
-
 If we would like to review the almanac data (i.e. default
 ``update_values=False``) and then decide to add them to our :class:`SkyCalc`
 object, the easiest way is with the :meth:`.update` method::
@@ -190,20 +201,20 @@ In full we have:
 .. plot::
     :include-source:
 
-    >>> import matplotlib.pyplot as plt
-    >>> from skycalc_ipy import SkyCalc
-    >>>
-    >>> skycalc = SkyCalc()
-    >>> skycalc.get_almanac_data(ra=83.8221, dec=-5.3911,
-    ...                          date="2017-12-24T04:00:00",
-    ...                          update_values=True)
-    >>> # skycalc["msolflux"] = 130       # [sfu] For dates after 2019-01-31
-    >>> tbl = skycalc.get_sky_spectrum()
-    >>>
-    >>> plt.plot(tbl["lam"], tbl["flux"])
-    >>> plt.xlabel("Wavelength " + str(tbl["lam"].unit))
-    >>> plt.ylabel("Flux " + str(tbl["flux"].unit))
-    >>> plt.semilogy()
+    import matplotlib.pyplot as plt
+    from skycalc_ipy import SkyCalc
+
+    skycalc = SkyCalc()
+    skycalc.get_almanac_data(ra=83.8221, dec=-5.3911,
+                             date="2017-12-24T04:00:00",
+                             update_values=True)
+    # skycalc["msolflux"] = 130       # [sfu] For dates after 2019-01-31
+    tbl = skycalc.get_sky_spectrum()
+
+    plt.semilogy(tbl["lam"], tbl["flux"])
+    plt.xlabel(f"Wavelength [{tbl['lam'].unit}]")
+    plt.ylabel(f"Flux [{tbl['flux'].unit}]")
+    plt.grid(True, ls=":")
 
 
 Customs lists of values

docs/source/index.rst

@@ -34,38 +34,54 @@ on the ESO SkyCalc server. For references to SkyCalc see `ESO SkyCalc`_,
    GettingStarted
    Reference API <reference/skycalc_ipy>
 
-.. note:: v0.2.0: Hotfix for new ESO ETC server.
+.. versionchanged:: v0.4.0
 
-    The new ESO ETC server uses different units, which are now used.
+   Drop support for Python 3.8.
 
-.. note:: v0.1.5: Hotfix to replace ESO ETC server URL.
+.. versionchanged:: v0.2.0
 
-    Skycalc now uses https://etimecalret-002.eso.org as server, #25.
+   Hotfix for new ESO ETC server.
 
-.. note:: v0.1.4: Drop support for Python 3.7.
+   The new ESO ETC server uses different units, which are now used.
 
-    Skycalc now uses `pyproject.toml`, and only supports Python 3.8+.
+.. versionchanged:: v0.1.5
 
-.. note:: v0.1.3: Updated default values for `wmax`, `wgrid_mode`, `wres`
+   Hotfix to replace ESO ETC server URL.
 
-    SkyCalc-ipy now uses a logarithmic wavelength binning with R=1000 over the
-    fully available SkyCalc wavelength range of [0.3, 30] um
+   Skycalc now uses https://etimecalret-002.eso.org as server, #25.
 
-    - `wmax`: --> `30000  # [nm]`
-    - `wgrid_mode`: --> `fixed_spectral_resolution`
-    - `wres`: --> `1000  wave/dwave`
+.. versionchanged:: v0.1.4
 
-.. note:: v0.1.3: No longer saves a temporary FITS file to disk.
+   Drop support for Python 3.7.
 
-    SkyCalc now uses astropy to download the fits file from the SkyCalc server.
-    The HDUList is now stored internally in `<SkyCalc>.last_skycalc_response`.
+   Skycalc now uses `pyproject.toml`, and only supports Python 3.8+.
 
-.. note:: v0.1.2: Upgrade fixes PyYaml warning/error for PyYaml >=6.0
+.. versionchanged:: v0.1.3
 
-    SkyCalc-ipy v0.1.1 is only compatible with versions of PyYaml <=5.4.
-    PyYaml v6+ removed backwards compatibility by forcing the user to pass a
-    Loader object when reading YAML files. SkyCalc-ipy v0.1.0 and v0.1.1 does
-    not do this.
+   Updated default values for `wmax`, `wgrid_mode`, `wres`
+
+   SkyCalc-ipy now uses a logarithmic wavelength binning with R=1000 over the
+   fully available SkyCalc wavelength range of [0.3, 30] um
+
+   - `wmax`: --> `30000  # [nm]`
+   - `wgrid_mode`: --> `fixed_spectral_resolution`
+   - `wres`: --> `1000  wave/dwave`
+
+.. versionchanged:: v0.1.3
+
+   No longer saves a temporary FITS file to disk.
+
+   SkyCalc now uses astropy to download the fits file from the SkyCalc server.
+   The HDUList is now stored internally in `<SkyCalc>.last_skycalc_response`.
+
+.. versionchanged:: v0.1.2
+
+   Upgrade fixes PyYaml warning/error for PyYaml >=6.0
+
+   SkyCalc-ipy v0.1.1 is only compatible with versions of PyYaml <=5.4.
+   PyYaml v6+ removed backwards compatibility by forcing the user to pass a
+   Loader object when reading YAML files. SkyCalc-ipy v0.1.0 and v0.1.1 does
+   not do this.
 
 
 Installation