3 docstrings related to pycbc.types.angle_as_radians (#5017)

* pycbc.types.angle_as_radians, pycbc_pygrb_grb_info_table, pycbc_make_sky_grid docstrings

* Better docstring

* Update pycbc/types/optparse.py

Co-authored-by: Tito Dal Canton <[email protected]>

---------

Co-authored-by: Tito Dal Canton <[email protected]>

bin/pycbc_make_sky_grid

@@ -9,6 +9,9 @@ statistics.
 
 The grid is constructed following the method described in Section V of
 https://arxiv.org/abs/1410.6042.
+
+Please refer to help(pycbc.types.angle_as_radians) for the recommended
+configuration file syntax for angle arguments.
 """
 
 import numpy as np

bin/pygrb/pycbc_pygrb_grb_info_table

@@ -16,7 +16,11 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 
-"""Create GRB info table."""
+"""Create GRB info table.
+
+Please refer to help(pycbc.types.angle_as_radians) for the recommended
+configuration file syntax for angle arguments.
+"""
 
 # =============================================================================
 # Preamble

pycbc/types/optparse.py

@@ -545,6 +545,15 @@ def angle_as_radians(s):
     (e.g. 12deg, 1rad), "<value> <unit>" (e.g. 12 deg, 1 rad) or just
     "<value>", in which case the unit will be assumed to be radians.
 
+    Note that the format "<value><unit>", with a negative value and no space,
+    is not parsed correctly by argparse; for more information, see
+    https://stackoverflow.com/questions/16174992/cant-get-argparse-to-read-quoted-string-with-dashes-in-it
+
+    Note: when writing angles in workflow configuration files as options to be
+    passed to executables that rely on this function and require angles in their
+    command line, the format "<value> <unit>", with the quotation marks
+    included, is required due to how Pegasus renders options in .sh files.
+
     To be used as type in argparse arguments.
     """
     # if `s` converts to a float then there is no unit, so assume radians