Update docs and build environment

.env.template

@@ -0,0 +1,8 @@
+# Template environment file for building the docs
+# Copy this to .env, then edit all indicated lines
+
+# Documentation Settings
+export DOCS_ROOT="path/to/dysh/docs"    # EDIT ME
+export DOCS_HOST=""                     # EDIT ME
+export DOCS_PORT=""                     # EDIT ME
+alias startdocs="cd $DOCS_ROOT && cd source && sphinx-autobuild . _build -b html --host $DOCS_HOST --port $DOCS_PORT"

docs/source/conf.py

@@ -44,7 +44,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    #"myst_parser",
+    "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
     "sphinx.ext.graphviz",
@@ -81,8 +81,7 @@
 #
 source_suffix = {
     '.rst':'restructuredtext',
-    '.md':'myst-nb', 
-    '.ipynb':'myst-nb'
+    '.md': 'markdown',
     }
 #source_suffix = {
 #    '.rst': 'restructuredtext',

docs/source/examples/positionswitch.rst

@@ -5,17 +5,20 @@ Position-Switched Data
 Background
 ==========
 
-Position switched observations are those in which the telescope observes a target (the ON position or signal) and another part of the sky, assumed to be devoid of emission (the OFF position or reference).
+Position-switched observations are those in which the telescope observes a target (the ON position or signal) and another part of the sky, assumed to be devoid of emission (the OFF position or reference).
 
-.. image:: ../_static/examples/gbt_ps_2.gif
+.. figure:: .img/gbt_ps_2.gif
+    :alt: A GIF showing the GBT nod back and forth in elevation to demonstrate position switching. 
 
 While observing this is accomplished using the functions `OnOff` or `OffOn` in a scheduling block. For more details about these functions see Sections 6.4.2.2 and 6.4.2.3 of the |gbtog_link|.
 
 .. |gbtog_link| raw:: html
 
    <a href="http://www.gb.nrao.edu/scienceDocs/GBTog.pdf" target="_blank">GBT observer's guide</a>
 
-A modified version of the scheduling block for the observations used in this example is copied below::
+A modified version of the scheduling block for the observations used in this example is copied below
+
+.. code:: python
 
     # Observing script for NGC 2415
 
@@ -86,60 +89,75 @@ A modified version of the scheduling block for the observations used in this exa
 Calibrating Position-Switched Data
 ==================================
 
-Single beam position-switched (PS) data is retrieved using :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.getps` which returns a :class:`~dysh.spectra.scan.GBTPSScan` position-switched scan object that is used to calibrate and average the data.  First, import the relevant modules::
+Single beam position-switched (PS) data is retrieved using :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.getps` which returns a :class:`~dysh.spectra.scan.GBTPSScan` position-switched scan object that is used to calibrate and average the data.  First, import the relevant modules
+
+.. code:: python
 
     >>> from dysh.fits.gbtfitsload import GBTFITSLoad
     >>> import astropy.units as u
 
 ..  (TODO need to replace fixed path with get_example_data() and explanation thereof)::
 
 Then load your SDFITS file containing PS data. In this example, we use a 
-`GBT SDFITS file downloadable from GBO <http://www.gb.nrao.edu/dysh/example_data/onoff-L/data/TGBT21A_501_11.raw.vegas.fits>`_::
+`GBT SDFITS file downloadable from GBO <http://www.gb.nrao.edu/dysh/example_data/onoff-L/data/TGBT21A_501_11.raw.vegas.fits>`_
+
+.. code:: python
 
     >>> f = 'TGBT21A_501_11.raw.vegas.fits'
     >>> sdfits = GBTFITSLoad(f)
 
-The returned `sdfits` can be probed for information::
+The returned `sdfits` can be probed for information
+
+.. code:: python
 
     >>> sdfits.info()
         Filename: /data/gbt/examples/onoff-L/data/TGBT21A_501_11.raw.vegas.fits
         No.    Name      Ver    Type      Cards   Dimensions   Format
           0  PRIMARY       1 PrimaryHDU      12   ()      
           1  SINGLE DISH    1 BinTableHDU    245   6040R x 74C   ['32A', '1D', '22A', '1D', '1D', '1D', '32768E', '16A', '6A', '8A', '1D', '1D', '1D', '4A', '1D', '4A', '1D', '1I', '32A', '32A', '1J', '32A', '16A', '1E', '8A', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '8A', '1D', '1D', '12A', '1I', '1I', '1D', '1D', '1I', '1A', '1I', '1I', '16A', '16A', '1J', '1J', '22A', '1D', '1D', '1I', '1A', '1D', '1E', '1D', '1D', '1D', '1D', '1D', '1A', '1A', '8A', '1E', '1E', '16A', '1I', '1I', '1I']   
 
-You can also print a concise (or verbose if you choose `verbose=True`) summary :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data::
+You can also print a concise (or verbose if you choose `verbose=True`) summary :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data
 
+.. code:: python
 
     >>> sdfits.summary()
         SCAN   OBJECT VELOCITY   PROC PROCSEQN  RESTFREQ   DOPFREQ # IF # POL # INT # FEED     AZIMUTH   ELEVATIO
     0    152  NGC2415   3784.0  OnOff        1  1.617185  1.420406    5     2   151      1  286.218008   41.62843
     1    153  NGC2415   3784.0  OnOff        2  1.617185  1.420406    5     2   151      1  286.886521  41.118134
 
-Retrieve a scan and its partner ON or OFF, selecting an IF number and polarization, then calibrate it::
+Retrieve a scan and its partner ON or OFF, selecting an IF number and polarization, then calibrate it
+
+.. code:: python
 
     >>> psscan = sdfits.getps(152, ifnum=0, plnum=0)
     >>> psscan.calibrate() # this will be eventually be subsumed into `calibrate=True` in `getps`
         PSSCAN nrows = 302
     
-The system temperature array (`numpy.ndarray`) is stored in `tsys`::
+The system temperature array (`numpy.ndarray`) is stored in `tsys`
+
+.. code:: python
 
     >>> print(f"T_sys = {pscan.tsys.mean():.2f} K")
         T_sys = 17.17 K
 
-Then time average the data, using system temperature weighting (other option is 'equal' weighting; 'tsys' is the default if no `weights` parameter is given. Future upgrade will allow the user to provide a numeric weights array). The returned object is :class:`~dysh.spectra.spectrum.Spectrum`, which has a default `matplotlib`-based plotter attached::
+Then time average the data, using system temperature weighting (other option is 'equal' weighting; 'tsys' is the default if no `weights` parameter is given. Future upgrade will allow the user to provide a numeric weights array). The returned object is :class:`~dysh.spectra.spectrum.Spectrum`, which has a default `matplotlib`-based plotter attached
 
+.. code:: python
 
     >>> ta = psscan.timeaverage(weights='tsys')
     >>> ta.plot()
 
-.. image:: ../_static/examples/ps_152.png
+.. figure:: img/ps_152.png
+    :alt: A frequency versus temperature spectrum plot. The spectrum is noisy and spans 1.390 to 1.415 GHz. 
 
+The :meth:`~dysh.spectra.spectrum.Spectrum.plot` command allows changing of axis units and also recognizes a number matplolib-like keywords
 
-The :meth:`~dysh.spectra.spectrum.Spectrum.plot` command allows changing of axis units and also recognizes a number matplolib-like keywords::
+.. code:: python
 
     >>> ta.plot(xaxis_unit="km/s",yaxis_unit="mK",ymin=-100,ymax=500,xmin=3000,xmax=4500)
 
-.. image:: ../_static/examples/ps_152_zoom.png
+.. figure:: img/ps_152_zoom.png
+    :alt: The spectrum plot zoomed in along both axes to frame a central emission line. 
 
 .. WARNING::
     At this point, `dysh` does not handle Doppler corrections. So the frequency and velocity information will be wrong for observations requesting a reference frame other than Topocentric.
@@ -151,6 +169,8 @@ Removing a baseline
 Baselines can be removed from :class:`~dysh.spectra.spectrum.Spectrum` with the :meth:`~dysh.spectra.spectrum.Spectrum.baseline` function.   Users provide baseline degree and optionally exclude region in any conformable x-axis unit (e.g., frequency, velocity, channel).  The default model is polynomial (:class:`~astropy.modeling.polynomial.Polynomial1D`) but a Chebyshev series (:class:`~astropy.modeling.polynomial.Chebyshev1D`)
 is also .  The baseline is removed if `remove=True`. 
 
+.. code:: python
+    
     >>> kms = u.km/u.s
     >>> ta.baseline(order=2,exclude=[3600,4100]*kms, remove=True)
     EXCLUDING [Spectral Region, 1 sub-regions:
@@ -168,5 +188,5 @@ is also .  The baseline is removed if `remove=True`.
         ------------------- --------------------- ----------------------
         0.16984671256725348 6.155580136474429e-29 2.2305011385559243e-56
 
-.. image:: ../_static/examples/ps_152_baseline_removed.png
-
+.. figure:: img/ps_152_baseline_removed.png
+    :alt: A plot of a spectrum after its baseline was removed.

docs/source/examples/subbeamnod.rst

@@ -7,7 +7,9 @@ SubBeamNod scans with the GBT consist of using the subreflector to alternate bet
 Calibrating SubBeamNod Data
 ===========================
 
-For this example we will be using data from a receiver checkout, TRCO_230413_Ka. The data can be downloaded from this `link <http://www.gb.nrao.edu/dysh/example_data/subbeamnod-Ka/data/TRCO_230413_Ka.raw.vegas/TRCO_230413_Ka.raw.vegas.A.fits>`_. Or, using `wget`::
+For this example we will be using data from a receiver checkout, TRCO_230413_Ka. The data can be downloaded from this `link <http://www.gb.nrao.edu/dysh/example_data/subbeamnod-Ka/data/TRCO_230413_Ka.raw.vegas/TRCO_230413_Ka.raw.vegas.A.fits>`_. Or, using `wget`
+
+.. code:: python
 
     >>> import wget
     >>> url = "http://www.gb.nrao.edu/dysh/example_data/subbeamnod-Ka/data/TRCO_230413_Ka.raw.vegas/TRCO_230413_Ka.raw.vegas.A.fits"
@@ -17,26 +19,34 @@ For this example we will be using data from a receiver checkout, TRCO_230413_Ka.
 
 SubBeamNod data is retrieved using :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.subbeamnod` which returns a :class:`~dysh.spectra.spectra.Spectrum` object.
 
-First, import the relevant module::
+First, import the relevant module
+
+.. code:: python
 
     >>> from dysh.fits.gbtfitsload import GBTFITSLoad
 
 ..  (TODO need to replace fixed path with get_example_data() and explanation thereof)::
 
-Then load your SDFITS file containing SubBeamNod data::
+Then load your SDFITS file containing SubBeamNod data
+
+.. code:: python
 
     >>> filename = 'TRCO_230413_Ka.raw.vegas.A.fits'
     >>> sdfits = GBTFITSLoad(filename)
 
-The returned `sdfits` can be probed for information::
+The returned `sdfits` can be probed for information
+
+.. code:: python
 
     >>> sdfits.info()
     Filename: /data/gbt/examples/subbeamnod-Ka/data/TRCO_230413_Ka.raw.vegas/TRCO_230413_Ka.raw.vegas.A.fits
     No.    Name      Ver    Type      Cards   Dimensions   Format
       0  PRIMARY       1 PrimaryHDU      12   ()      
       1  SINGLE DISH    1 BinTableHDU    245   5280R x 74C   ['32A', '1D', '22A', '1D', '1D', '1D', '1024E', '16A', '6A', '8A', '1D', '1D', '1D', '4A', '1D', '4A', '1D', '1I', '32A', '32A', '1J', '32A', '16A', '1E', '8A', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '8A', '1D', '1D', '12A', '1I', '1I', '1D', '1D', '1I', '1A', '1I', '1I', '16A', '16A', '1J', '1J', '22A', '1D', '1D', '1I', '1A', '1D', '1E', '1D', '1D', '1D', '1D', '1D', '1A', '1A', '8A', '1E', '1E', '16A', '1I', '1I', '1I']   
 
-You can also print a concise (or verbose if you choose `verbose=True`) :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data::
+You can also print a concise (or verbose if you choose `verbose=True`) :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data
+
+.. code:: python
 
     >>> sdfits.summary()
         SCAN     OBJECT VELOCITY        PROC  PROCSEQN RESTFREQ DOPFREQ # IF # POL # INT # FEED     AZIMUTH   ELEVATIO
@@ -59,7 +69,9 @@ You can also print a concise (or verbose if you choose `verbose=True`) :meth:`~d
     16    53  1256-0547      0.0         Nod         2     30.5    30.5    1     2    60      2  170.175815  45.201877
     17    54  1256-0547      0.0  SubBeamNod         1     30.5    30.5    1     2   120      2  170.518885  45.232575
 
-The SubBeamNod scans are 43, 46, and 54.  Retrieve and calibrate a SubBeamNod scan, then plot it::
+The SubBeamNod scans are 43, 46, and 54.  Retrieve and calibrate a SubBeamNod scan, then plot it
+
+.. code:: python
 
     >>> sbn = sdfits.subbeamnod(scan=43, fdnum=1, ifnum=0, weights='tsys')
     >>> sbn.plot()

docs/source/examples/totalpower.rst

@@ -5,40 +5,52 @@ Total Power Data
 Retrieving and Viewing a Total Power Scan
 =========================================
 
-Single beam total power (TP) data is retrieved using :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.gettp` which returns a :class:`~dysh.spectra.scan.GBTTPScan` total power scan object that is used to calibrate and average the data.  First, import the relevant module::
+Single beam total power (TP) data is retrieved using :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.gettp` which returns a :class:`~dysh.spectra.scan.GBTTPScan` total power scan object that is used to calibrate and average the data.  First, import the relevant module
+
+.. code:: python
 
     >>> from dysh.fits.gbtfitsload import GBTFITSLoad
     >>> import numpy as np
 
 ..  (TODO need to replace fixed path with get_example_data() and explanation thereof)::
 
 Then load your SDFITS file containing TP data. In this example, we use a 
-`GBT SDFITS file downloadable from GBO <http://www.gb.nrao.edu/dysh/example_data/onoff-L/data/TGBT21A_501_11.raw.vegas.fits>`_::
+`GBT SDFITS file downloadable from GBO <http://www.gb.nrao.edu/dysh/example_data/onoff-L/data/TGBT21A_501_11.raw.vegas.fits>`_
+
+.. code:: python
 
     >>> f = 'TGBT21A_501_11.raw.vegas.fits'
     >>> sdfits = GBTFITSLoad(f)
 
-The returned `sdfits` can be probed for information::
+The returned `sdfits` can be probed for information
+
+.. code:: python
 
     >>> sdfits.info()
         Filename: /data/gbt/examples/onoff-L/data/TGBT21A_501_11.raw.vegas.fits
         No.    Name      Ver    Type      Cards   Dimensions   Format
           0  PRIMARY       1 PrimaryHDU      12   ()      
           1  SINGLE DISH    1 BinTableHDU    245   6040R x 74C   ['32A', '1D', '22A', '1D', '1D', '1D', '32768E', '16A', '6A', '8A', '1D', '1D', '1D', '4A', '1D', '4A', '1D', '1I', '32A', '32A', '1J', '32A', '16A', '1E', '8A', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '1D', '8A', '1D', '1D', '12A', '1I', '1I', '1D', '1D', '1I', '1A', '1I', '1I', '16A', '16A', '1J', '1J', '22A', '1D', '1D', '1I', '1A', '1D', '1E', '1D', '1D', '1D', '1D', '1D', '1A', '1A', '8A', '1E', '1E', '16A', '1I', '1I', '1I']   
 
-You can also print a concise (or verbose if you choose `verbose=True`) summary :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data::
+You can also print a concise (or verbose if you choose `verbose=True`) summary :meth:`~dysh.fits.gbtfitsload.GBTFITSLoad.summary` of the data
+
+.. code:: python
 
     >>> sdfits.summary()
         SCAN   OBJECT VELOCITY   PROC PROCSEQN  RESTFREQ   DOPFREQ # IF # POL # INT # FEED     AZIMUTH   ELEVATIO
     0  152.0  NGC2415   3784.0  OnOff      1.0  1.617185  1.420406    5     2   151      1  286.218008   41.62843
     1  153.0  NGC2415   3784.0  OnOff      2.0  1.617185  1.420406    5     2   151      1  286.886521  41.118134
 
-Retrieve a scan, selecting and IF number and polarization::
+Retrieve a scan, selecting and IF number and polarization
+
+.. code:: python
 
     >>> tpscan = sdfits.gettp(152, ifnum=0, plnum=0)
         TPSCAN nrows = 302
 
-The `~dysh.spectra.scan.GBTTPScan` contains the individual integrations.  The system temperatures per integration are calculated from the CALON and CALOFF data::
+The `~dysh.spectra.scan.GBTTPScan` contains the individual integrations.  The system temperatures per integration are calculated from the CALON and CALOFF data
+
+.. code:: python
 
     >>> print('%s' % (np.array2string(tps.tsys,precision=2)))
         [16.89 16.89 16.94 16.77 16.96 16.94 16.87 16.86 16.92 16.86 16.85 16.97
@@ -55,8 +67,11 @@ The `~dysh.spectra.scan.GBTTPScan` contains the individual integrations.  The sy
          17.04 16.88 16.9  17.03 16.9  16.84 16.99 16.95 16.94 17.02 17.01 16.91
          16.95 16.91 16.92 17.08 16.67 17.06 17.14]
 
-You can time-average the data, in this example with equal weighting per integration, and plot it::
+You can time-average the data, in this example with equal weighting per integration, and plot it
+
+.. code:: python
 
     >>> tps.timeaverage(weights=None).plot()
 
-.. image:: ../_static/examples/tp_153_eqweight.png
+.. figure:: img/tp_153_eqweight.png
+    :alt: A plot of the time-averaged data

docs/source/for_developers/black.rst

@@ -0,0 +1,38 @@
+****************
+Black Formatting
+****************
+
+VSCode
+=================
+
+If you are developing in VSCode, you can install `black` directly into the IDE and have it run every time you save a Python file. 
+
+1. Download the Black Formatter Extension by Microsoft
+
+.. figure:: img/VSCode_Black_Installer.png
+    :alt: A screenshot of the VSCode extension installer with the Black formatter selected
+
+2. (Optional) Download the Prettier Formatter
+
+`Prettier` will format files in languages besides Python. It is not required for `dysh`, but it does make it look nicer. 
+
+.. figure:: img/VSCode_Prettier_Installer.png
+    :alt: A screenshot of the VSCode extension installer with the Prettier formatter selected
+
+3. Check the VSCode Project Settings
+
+The JSON file ``dysh/.vscode/settings.json`` contains VSCode settings for this project. The contents are as follows:
+
+.. code-block:: json
+
+    {
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.formatOnSave": true,
+        "[python]": {
+            "editor.defaultFormatter": "ms-python.black-formatter",
+            "editor.formatOnSave": true
+        },
+        "python.formatting.blackArgs": ["--line-length 120"]
+    }
+
+If you did not install `Prettier`, delete the first two entries. If you do not want certain languages to auto-format on every save, then set their corresponding ``"editor.defaultFormatter"`` to ``false``.

docs/source/for_developers/contributing.rst

@@ -0,0 +1,5 @@
+************
+Contributing
+************
+
+Want to contribute to `dysh`?