Docs updates based on PR comments

Other docs and import cleanups

docs/developer_docs.rst

@@ -40,8 +40,9 @@ the user classes and the file-specific classes automatically as needed, so users
 generally do not need to interact with these classes, but developers may need to.
 
 
-UVData
-******
+UVData Classes
+**************
+
 
 .. autoclass:: pyuvdata.uvdata.fhd.FHD
   :members:
@@ -64,8 +65,9 @@ UVData
 .. autoclass:: pyuvdata.uvdata.uvh5.UVH5
   :members:
 
-UVCal
-*****
+
+UVCal Classes
+*************
 
 .. autoclass:: pyuvdata.uvcal.calfits.CALFITS
   :members:
@@ -76,8 +78,8 @@ UVCal
 .. autoclass:: pyuvdata.uvcal.fhd_cal.FHDCal
   :members:
 
-UVBeam
-******
+UVBeam Classes
+**************
 
 .. autoclass:: pyuvdata.uvbeam.beamfits.BeamFITS
   :members:
@@ -89,182 +91,43 @@ UVBeam
   :members:
 
 
-.. _Developer Docs Utility Functions:
-
-Utility Functions
------------------
-Note that we are also listing private functions here (functions that start with
-an underscore). While they are listed here, **they are not considered part of the
-public API, so they can change without notice**. If you find that you need to rely
-one of them let us know in a github issue and we can consider making it part of
-the public API.
-
-
-File I/O Utility Functions
-**************************
-
-Antenna position files
-++++++++++++++++++++++
-
-.. automodule:: pyuvdata.utils.io.antpos
-  :members:
-  :private-members:
-  :undoc-members:
-
-FHD files
-+++++++++
-
-.. automodule:: pyuvdata.utils.io.fhd
-  :members:
-  :private-members:
-  :undoc-members:
-
-FITS files
-++++++++++
-
-.. automodule:: pyuvdata.utils.io.fits
-  :members:
-  :private-members:
-  :undoc-members:
-
-HDF5 files
-++++++++++
-
-.. automodule:: pyuvdata.utils.io.hdf5
-  :members:
-  :private-members:
-  :undoc-members:
-
-Measurement Set files
-+++++++++++++++++++++
-
-.. automodule:: pyuvdata.utils.io.ms
-  :members:
-  :private-members:
-  :undoc-members:
-
-Array collapse functions for flags
-**********************************
-
-.. automodule:: pyuvdata.utils.array_collapse
-  :members:
-  :private-members:
-  :undoc-members:
-
-Functions for working with baseline numbers
-*******************************************
-
-.. automodule:: pyuvdata.utils.bls
-  :members:
-  :private-members:
-  :undoc-members:
-  :ignore-module-all:
-
-Functions for working with the baseline-time axis
-*************************************************
-
-.. automodule:: pyuvdata.utils.bltaxis
-  :members:
-  :private-members:
-  :undoc-members:
-
-Functions for working with telescope coordinates
-************************************************
-
-.. automodule:: pyuvdata.utils.coordinates
-  :members:
-  :private-members:
-  :undoc-members:
-  :ignore-module-all:
-
-Functions for working with the frequency axis
-*********************************************
-
-.. automodule:: pyuvdata.utils.frequency
-  :members:
-  :private-members:
-  :undoc-members:
-
-Functions for working with history
-**********************************
-
-.. automodule:: pyuvdata.utils.history
-  :members:
-  :private-members:
-  :undoc-members:
-
-Functions for working with phase center catalogs
-************************************************
+Other Modules and Functions
+---------------------------
 
-.. automodule:: pyuvdata.utils.phase_center_catalog
-  :members:
-  :private-members:
-  :undoc-members:
-
-Functions for working with phasing
-**********************************
-
-.. automodule:: pyuvdata.utils.phasing
-  :members:
-  :private-members:
-  :undoc-members:
+MWA Beam Functions
+******************
+Functions related to constructing the MWA beam from the input files which are in
+a harmonic space.
 
-Functions for working with polarizations
-****************************************
+.. autofunction:: pyuvdata.uvbeam.mwa_beam.P1sin
 
-.. automodule:: pyuvdata.utils.pol
-  :members:
-  :private-members:
-  :undoc-members:
-  :ignore-module-all:
+.. autofunction:: pyuvdata.uvbeam.mwa_beam.P1sin_array
 
-Functions for working with baseline redundancies
-************************************************
 
-.. automodule:: pyuvdata.utils.redundancy
-  :members:
-  :private-members:
-  :undoc-members:
-
-Functions for working with times and LSTs
-*****************************************
+aipy extracts
+*************
 
-.. automodule:: pyuvdata.utils.times
+.. automodule:: pyuvdata.uvdata.aipy_extracts
   :members:
-  :private-members:
-  :undoc-members:
 
-General utility functions
-*************************
 
-.. automodule:: pyuvdata.utils.tools
-  :members:
-  :private-members:
-  :undoc-members:
+MIR parser
+**********
 
-Mir Parser
-----------
 .. automodule:: pyuvdata.uvdata.mir_parser
   :members:
 
+MIR metadata
+************
+
 .. automodule:: pyuvdata.uvdata.mir_meta_data
   :members:
 
 
-Other Functions
----------------
-
-.. autofunction:: pyuvdata.uvbeam.mwa_beam.P1sin
-
-.. autofunction:: pyuvdata.uvbeam.mwa_beam.P1sin_array
+UVFlag Functions
+****************
+Flag handling functions.
 
 .. autofunction:: pyuvdata.uvflag.uvflag.and_rows_cols
 
 .. autofunction:: pyuvdata.uvflag.uvflag.flags2waterfall
-
-
-aipy extracts
--------------
-
-.. automodule:: pyuvdata.uvdata.aipy_extracts
-  :members:

docs/make_index.py

@@ -52,7 +52,7 @@ def write_index_rst(readme_file=None, write_file=None):
         "   telescope\n"
         "   fast_uvh5_meta\n"
         "   fast_calh5_meta\n"
-        "   functions\n"
+        "   utility_functions\n"
         "   developer_docs\n"
     )
 

docs/make_telescope.py

@@ -44,13 +44,6 @@ def write_telescope_rst(write_file=None):
         "`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 += (
@@ -90,7 +83,8 @@ def write_telescope_rst(write_file=None):
         ":class:`astropy.coordinates.EarthLocation` object, which\n"
         "is shown here using the Geodetic representation. Also 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"
+        "which can be used if data files are missing that information.\n"
+        "We also provide a convenience function to get known telescope locations.\n\n"
     )
 
     known_tel_use = copy.deepcopy(_KNOWN_TELESCOPES)
@@ -104,6 +98,8 @@ def write_telescope_rst(write_file=None):
     json_obj = json_obj[:-1] + " }"
     out += ".. code-block:: JavaScript\n\n {json_str}\n\n".format(json_str=json_obj)
 
+    out += ".. autofunction:: pyuvdata.telescopes.known_telescope_location\n\n"
+
     t = Time.now()
     t.format = "iso"
     t.out_subfmt = "date"

docs/make_uvcal.py

@@ -53,11 +53,6 @@ def write_uvcal_rst(write_file=None):
         "``delay_array``, ``flag_array``, ``quality_array``) are not. The\n"
         ":meth:`pyuvdata.UVCal.check` method will still pass for metadata only\n"
         "objects.\n\n"
-        "Note location type attributes (which are given in topocentric xyz\n"
-        "coordinates) have convenience properties named the same thing with\n"
-        "``_lat_lon_alt`` and ``_lat_lon_alt_degrees`` appended through which you can\n"
-        "get or set the values using latitude, longitude and altitude values in\n"
-        "radians or degrees and meters.\n\n"
     )
     out += "Required\n********\n"
     out += (

docs/make_uvdata.py

@@ -49,13 +49,9 @@ def write_uvdata_rst(write_file=None):
         "``flag_array``, ``nsample_array``) are not. The\n"
         ":meth:`pyuvdata.UVData.check` method will still pass for metadata only\n"
         "objects.\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"
+        "Note that angle type attributes also have convenience properties named\n"
+        "the same thing with ``_degrees`` appended through which you can get or\n"
+        "set the value in degrees.\n\n"
     )
     out += "Required\n********\n"
     out += (