Update the docs for the telescope refactor

.gitignore

@@ -60,6 +60,7 @@ docs/uvdata.rst
 docs/uvcal.rst
 docs/uvbeam.rst
 docs/uvflag.rst
+docs/telescope.rst
 
 # PyBuilder
 target/

docs/conf.py

@@ -32,6 +32,7 @@
 uvcal_file = os.path.join(os.path.abspath("../docs"), "uvcal.rst")
 uvbeam_file = os.path.join(os.path.abspath("../docs"), "uvbeam.rst")
 uvflag_file = os.path.join(os.path.abspath("../docs"), "uvflag.rst")
+telescope_file = os.path.join(os.path.abspath("../docs"), "telescope.rst")
 
 # -- General configuration ------------------------------------------------
 
@@ -347,12 +348,14 @@ def build_custom_docs(app):
     import make_uvcal
     import make_uvbeam
     import make_uvflag
+    import make_telescope
 
     make_index.write_index_rst(readme_file=readme_file, write_file=index_file)
     make_uvdata.write_uvdata_rst(write_file=uvdata_file)
     make_uvcal.write_uvcal_rst(write_file=uvcal_file)
     make_uvbeam.write_uvbeam_rst(write_file=uvbeam_file)
     make_uvflag.write_uvflag_rst(write_file=uvflag_file)
+    make_telescope.write_telescope_rst(write_file=telescope_file)
 
 
 # this is to enable running python in the rst files.

docs/fast_calh5_meta.rst

@@ -0,0 +1,5 @@
+FastCalH5Meta
+=================
+
+.. autoclass:: pyuvdata.uvcal.FastCalH5Meta
+   :members:

docs/make_index.py

@@ -49,9 +49,10 @@ def write_index_rst(readme_file=None, write_file=None):
         "   uvcal\n"
         "   uvbeam\n"
         "   uvflag\n"
+        "   telescope\n"
         "   fast_uvh5_meta\n"
+        "   fast_calh5_meta\n"
         "   utility_functions\n"
-        "   known_telescopes\n"
         "   developer_docs\n"
     )
 

docs/make_telescope.py

@@ -0,0 +1,96 @@
+# -*- mode: python; coding: utf-8 -*-
+
+"""
+Format the Telescope object parameters into a sphinx rst file.
+
+"""
+import inspect
+import json
+import os
+
+from astropy.time import Time
+
+from pyuvdata import Telescope
+from pyuvdata.telescopes import KNOWN_TELESCOPES
+
+
+def write_telescope_rst(write_file=None):
+    tel = Telescope()
+    out = "Telescope\n=========\n\n"
+    out += (
+        "Telescope is a helper class for telescope-related metadata.\n"
+        "Several of the primary user classes need telescope metdata, so they "
+        "have a Telescope object as an attribute.\n\n"
+        "Attributes\n----------\n"
+        "The attributes on Telescope hold all of the metadata required to\n"
+        "describe interferometric telescopes. Under the hood, the attributes are\n"
+        "implemented as properties based on :class:`pyuvdata.parameter.UVParameter`\n"
+        "objects but this is fairly transparent to users.\n\n"
+        "When a new Telescope object is initialized, it has all of these \n"
+        "attributes defined but set to ``None``. The attributes\n"
+        "can be set directly on the object. Some of these attributes\n"
+        "are `required`_ to be set to have a fully defined object while others are\n"
+        "`optional`_. The :meth:`pyuvdata.Telescope.check` method can be called\n"
+        "on the object to verify that all of the required attributes have been\n"
+        "set in a consistent way.\n\n"
+        "Note that angle type attributes also have convenience properties named the\n"
+        "same thing with ``_degrees`` appended through which you can get or set the\n"
+        "value in degrees. Similarly location type attributes (which are given in\n"
+        "geocentric xyz coordinates) have convenience properties named the\n"
+        "same thing with ``_lat_lon_alt`` and ``_lat_lon_alt_degrees`` appended\n"
+        "through which you can get or set the values using latitude, longitude and\n"
+        "altitude values in radians or degrees and meters.\n\n"
+    )
+    out += "Required\n********\n"
+    out += (
+        "These parameters are required to have a basic well-defined Telescope object.\n"
+    )
+    out += "\n\n"
+    for thing in tel.required():
+        obj = getattr(tel, thing)
+        out += "**{name}**\n".format(name=obj.name)
+        out += "     {desc}\n".format(desc=obj.description)
+        out += "\n"
+
+    out += "Optional\n********\n"
+    out += (
+        "These parameters are needed by by one or of the primary user classes\n"
+        "but are not always required. Some of them are required when attached to\n"
+        "the primary classes."
+    )
+    out += "\n\n"
+
+    for thing in tel.extra():
+        obj = getattr(tel, thing)
+        out += "**{name}**\n".format(name=obj.name)
+        out += "     {desc}\n".format(desc=obj.description)
+        out += "\n"
+
+    out += "Methods\n-------\n.. autoclass:: pyuvdata.Telescope\n  :members:\n\n"
+
+    out += (
+        "Known Telescopes\n================\n\n"
+        "Known Telescope Data\n--------------------\n"
+        "pyuvdata uses `Astropy sites\n"
+        "<https://docs.astropy.org/en/stable/api/astropy.coordinates."
+        "EarthLocation.html#astropy.coordinates.EarthLocation.get_site_names>`_\n"
+        "for telescope location information, in addition to the following\n"
+        "telescope information that is tracked within pyuvdata. Note that for\n"
+        "some telescopes we store csv files giving antenna layout information\n"
+        "which can be used if data files are missing that information.\n\n"
+    )
+
+    json_obj = json.dumps(KNOWN_TELESCOPES, sort_keys=True, indent=4)
+    json_obj = json_obj[:-1] + " }"
+    out += ".. code-block:: JavaScript\n\n {json_str}\n\n".format(json_str=json_obj)
+
+    t = Time.now()
+    t.format = "iso"
+    t.out_subfmt = "date"
+    out += "last updated: {date}".format(date=t.iso)
+    if write_file is None:
+        write_path = os.path.dirname(os.path.abspath(inspect.stack()[0][1]))
+        write_file = os.path.join(write_path, "telescope.rst")
+    F = open(write_file, "w")
+    F.write(out)
+    print("wrote " + write_file)

docs/make_uvbeam.py

@@ -43,7 +43,7 @@ def write_uvbeam_rst(write_file=None):
     )
     out += "Required\n********\n"
     out += (
-        "These parameters are required to have a sensible UVBeam object and \n"
+        "These parameters are required to have a well-defined UVBeam object and \n"
         "are required for most kinds of beam files."
     )
     out += "\n\n"

docs/make_uvcal.py

@@ -9,11 +9,12 @@
 
 from astropy.time import Time
 
-from pyuvdata import UVCal
+from pyuvdata import Telescope, UVCal
 
 
 def write_uvcal_rst(write_file=None):
     cal = UVCal()
+    cal.telescope = Telescope()
     out = "UVCal\n=====\n"
     out += (
         "UVCal is the main user class for calibration solutions for interferometric\n"
@@ -26,7 +27,9 @@ def write_uvcal_rst(write_file=None):
         "work with calibration solutions for interferometric data sets. Under the\n"
         "hood, the attributes are implemented as properties based on\n"
         ":class:`pyuvdata.parameter.UVParameter` objects but this is fairly\n"
-        "transparent to users.\n\n"
+        "transparent to users.\n"
+        "The telescope attribute is implemented as a :class:`pyuvdata.Telescope`\n"
+        "object, with its attributes available on the UVData object as properties.\n\n"
         "UVCal objects can be initialized as an empty object (as ``cal = UVCal()``).\n"
         "When an empty UVCal object is initialized, it has all of these attributes\n"
         "defined but set to ``None``. The attributes can be set by reading in a data\n"
@@ -49,7 +52,7 @@ def write_uvcal_rst(write_file=None):
     )
     out += "Required\n********\n"
     out += (
-        "These parameters are required to have a sensible UVCal object and \n"
+        "These parameters are required to have a well-defined UVCal object and \n"
         "are required for most kinds of uv cal files."
     )
     out += "\n\n"

docs/make_uvdata.py

@@ -9,11 +9,12 @@
 
 from astropy.time import Time
 
-from pyuvdata import UVData
+from pyuvdata import Telescope, UVData
 
 
 def write_uvdata_rst(write_file=None):
     UV = UVData()
+    UV.telescope = Telescope()
     out = "UVData\n======\n\n"
     out += (
         "UVData is the main user class for intereferometric data (visibilities).\n"
@@ -25,7 +26,9 @@ def write_uvdata_rst(write_file=None):
         "The attributes on UVData hold all of the metadata and data required to\n"
         "analyze interferometric data sets. Under the hood, the attributes are\n"
         "implemented as properties based on :class:`pyuvdata.parameter.UVParameter`\n"
-        "objects but this is fairly transparent to users.\n\n"
+        "objects but this is fairly transparent to users.\n"
+        "The telescope attribute is implemented as a :class:`pyuvdata.Telescope`\n"
+        "object, with its attributes available on the UVData object as properties.\n"
         "UVData objects can be initialized from a file using the\n"
         ":meth:`pyuvdata.UVData.from_file` class method\n"
         "(as ``uvd = UVData.from_file(<filename>)``) or be initialized as an empty\n"
@@ -45,14 +48,14 @@ def write_uvdata_rst(write_file=None):
         "Note that angle type attributes also have convenience properties named the\n"
         "same thing with ``_degrees`` appended through which you can get or set the\n"
         "value in degrees. Similarly location type attributes (which are given in\n"
-        "topocentric xyz coordinates) have convenience properties named the\n"
+        "geocentric xyz coordinates) have convenience properties named the\n"
         "same thing with ``_lat_lon_alt`` and ``_lat_lon_alt_degrees`` appended\n"
         "through which you can get or set the values using latitude, longitude and\n"
         "altitude values in radians or degrees and meters.\n\n"
     )
     out += "Required\n********\n"
     out += (
-        "These parameters are required to have a sensible UVData object and\n"
+        "These parameters are required to have a well-defined UVData object and\n"
         "are required for most kinds of interferometric data files."
     )
     out += "\n\n"

docs/make_uvflag.py

@@ -31,7 +31,9 @@ def write_uvflag_rst(write_file=None):
         "specify flagging and metric information for interferometric data sets.\n"
         "Under the hood, the attributes are implemented as properties based on\n"
         ":class:`pyuvdata.parameter.UVParameter` objects but this is fairly\n"
-        "transparent to users.\n\n"
+        "transparent to users.\n"
+        "The telescope attribute is implemented as a :class:`pyuvdata.Telescope`\n"
+        "object, with its attributes available on the UVData object as properties.\n\n"
         "UVFlag objects can be initialized from a file or a :class:`pyuvdata.UVData`\n"
         "or :class:`pyuvdata.UVCal` object\n"
         "(as ``flag = UVFlag(<filename or object>)``). Some of these attributes\n"
@@ -42,7 +44,7 @@ def write_uvflag_rst(write_file=None):
     )
     out += "Required\n********\n"
     out += (
-        "These parameters are required to have a sensible UVFlag object and \n"
+        "These parameters are required to have a well-defined UVFlag object and \n"
         "are required for most kinds of uv data files."
     )
     out += "\n\n"

pyuvdata/uvcal/uvcal.py

@@ -98,7 +98,10 @@ def __init__(self):
 
         self._telescope = uvp.UVParameter(
             "telescope",
-            description="Telescope object containing the telescope metadata.",
+            description=(
+                ":class:`pyuvdata.Telescope` object containing the telescope "
+                "metadata."
+            ),
             expected_type=Telescope,
         )
 

pyuvdata/uvdata/uvdata.py

@@ -537,7 +537,10 @@ def __init__(self):
 
         self._telescope = uvp.UVParameter(
             "telescope",
-            description="Telescope object containing the telescope metadata.",
+            description=(
+                ":class:`pyuvdata.Telescope` object containing the telescope "
+                "metadata."
+            ),
             expected_type=Telescope,
         )
 

pyuvdata/uvflag/uvflag.py

@@ -525,7 +525,10 @@ def __init__(
         # ---telescope information ---
         self._telescope = uvp.UVParameter(
             "telescope",
-            description="Telescope object containing the telescope metadata.",
+            description=(
+                ":class:`pyuvdata.Telescope` object containing the telescope "
+                "metadata."
+            ),
             expected_type=Telescope,
         )