From bfb65e8e39e51a12ff968e3ab93f91cc02686d87 Mon Sep 17 00:00:00 2001 From: Bryna Hazelton Date: Thu, 28 Mar 2024 16:35:15 -0700 Subject: [PATCH] Update the docs for the telescope refactor --- .gitignore | 1 + docs/conf.py | 3 ++ docs/fast_calh5_meta.rst | 5 ++ docs/known_telescopes.rst | 21 --------- docs/make_index.py | 3 +- docs/make_telescope.py | 96 +++++++++++++++++++++++++++++++++++++++ docs/make_uvbeam.py | 2 +- docs/make_uvcal.py | 9 ++-- docs/make_uvdata.py | 11 +++-- docs/make_uvflag.py | 6 ++- pyuvdata/uvcal/uvcal.py | 5 +- pyuvdata/uvdata/uvdata.py | 5 +- pyuvdata/uvflag/uvflag.py | 5 +- 13 files changed, 137 insertions(+), 35 deletions(-) create mode 100644 docs/fast_calh5_meta.rst delete mode 100644 docs/known_telescopes.rst create mode 100644 docs/make_telescope.py diff --git a/.gitignore b/.gitignore index c9674e47e2..52dc32d40f 100644 --- a/.gitignore +++ b/.gitignore @@ -60,6 +60,7 @@ docs/uvdata.rst docs/uvcal.rst docs/uvbeam.rst docs/uvflag.rst +docs/telescope.rst # PyBuilder target/ diff --git a/docs/conf.py b/docs/conf.py index 956eef141d..a3422bb211 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/fast_calh5_meta.rst b/docs/fast_calh5_meta.rst new file mode 100644 index 0000000000..3fecea1753 --- /dev/null +++ b/docs/fast_calh5_meta.rst @@ -0,0 +1,5 @@ +FastCalH5Meta +================= + +.. autoclass:: pyuvdata.uvcal.FastCalH5Meta + :members: diff --git a/docs/known_telescopes.rst b/docs/known_telescopes.rst deleted file mode 100644 index e5172b6910..0000000000 --- a/docs/known_telescopes.rst +++ /dev/null @@ -1,21 +0,0 @@ -Known Telescopes -================ - -Known Telescope Data --------------------- -pyuvdata uses `Astropy sites `_ -for telescope location information, in addition to the following telescope information -that is tracked within pyuvdata: - -.. exec:: - import json - from pyuvdata.telescopes import KNOWN_TELESCOPES - json_obj = json.dumps(KNOWN_TELESCOPES, sort_keys=True, indent=4) - json_obj = json_obj[:-1] + " }" - print('.. code-block:: JavaScript\n\n {json_str}\n\n'.format(json_str=json_obj)) - -Related class and functions ---------------------------- - -.. automodule:: pyuvdata.telescopes - :members: diff --git a/docs/make_index.py b/docs/make_index.py index a713bef015..a80bbdb673 100644 --- a/docs/make_index.py +++ b/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" ) diff --git a/docs/make_telescope.py b/docs/make_telescope.py new file mode 100644 index 0000000000..aa501799b9 --- /dev/null +++ b/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" + "`_\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) diff --git a/docs/make_uvbeam.py b/docs/make_uvbeam.py index 3f69b64ba5..f930a0f5e2 100644 --- a/docs/make_uvbeam.py +++ b/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" diff --git a/docs/make_uvcal.py b/docs/make_uvcal.py index 9aee25a6e5..d2384f279b 100644 --- a/docs/make_uvcal.py +++ b/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" diff --git a/docs/make_uvdata.py b/docs/make_uvdata.py index 7424afb329..c12581076d 100644 --- a/docs/make_uvdata.py +++ b/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()``) 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" diff --git a/docs/make_uvflag.py b/docs/make_uvflag.py index 135151ee10..7ac785cef7 100644 --- a/docs/make_uvflag.py +++ b/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()``). 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" diff --git a/pyuvdata/uvcal/uvcal.py b/pyuvdata/uvcal/uvcal.py index 437ad06673..dfb85950dd 100644 --- a/pyuvdata/uvcal/uvcal.py +++ b/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, ) diff --git a/pyuvdata/uvdata/uvdata.py b/pyuvdata/uvdata/uvdata.py index 60af50d418..dab82afbf5 100644 --- a/pyuvdata/uvdata/uvdata.py +++ b/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, ) diff --git a/pyuvdata/uvflag/uvflag.py b/pyuvdata/uvflag/uvflag.py index 8bcc6a040a..74a694e9f9 100644 --- a/pyuvdata/uvflag/uvflag.py +++ b/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, )