Improve docstring of x2sys_init and x2sys_cross (#930)

Co-authored-by: Dongdong Tian <[email protected]>
Co-authored-by: Wei Ji <[email protected]>

Author: 3 people

pygmt/x2sys.py

@@ -72,16 +72,15 @@ def x2sys_init(tag, **kwargs):
     r"""
     Initialize a new x2sys track database.
 
-    x2sys_init is the starting point for anyone wishing to use x2sys; it
-    initializes a set of data bases that are particular to one kind of track
-    data. These data, their associated data bases, and key parameters are given
-    a short-hand notation called an x2sys TAG. The TAG keeps track of settings
-    such as file format, whether the data are geographic or not, and the
-    binning resolution for track indices.
+    Serves as the starting point for x2sys and initializes a set of data bases
+    that are particular to one kind of track data. These data, their associated
+    data bases, and key parameters are given a short-hand notation called an
+    x2sys TAG. The TAG keeps track of settings such as file format, whether the
+    data are geographic or not, and the binning resolution for track indices.
 
-    Before you can run x2sys_init you must set the environmental parameter
-    X2SYS_HOME to a directory where you have write permission, which is where
-    x2sys can keep track of your settings.
+    Before you can run :meth:`pygmt.x2sys_init` you must set the environmental
+    parameter X2SYS_HOME to a directory where you have write permission, which
+    is where x2sys can keep track of your settings.
 
     Full option list at :gmt-docs:`supplements/x2sys/x2sys_init.html`
 
@@ -93,68 +92,69 @@ def x2sys_init(tag, **kwargs):
         The unique name of this data type x2sys TAG.
 
     fmtfile : str
-        Format definition file prefix for this data set [See Format Definition
-        Files for more information]. Specify full path if the file is not in
-        the current directory.
+        Format definition file prefix for this data set (see
+        :gmt-docs:`GMT's Format Definition Files
+        <supplements/x2sys/x2sys_init.html#format-definition-files>`
+        for more information). Specify full path if the file is not in the
+        current directory.
 
         Some file formats already have definition files premade. These include:
 
-        - mgd77 (for plain ASCII MGD77 data files)
-        - mgd77+ (for enhanced MGD77+ netCDF files)
-        - gmt (for old mgg supplement binary files)
-        - xy (for plain ASCII x, y tables)
-        - xyz (same, with one z-column)
-        - geo (for plain ASCII longitude, latitude files)
-        - geoz (same, with one z-column).
+        - **mgd77** (for plain ASCII MGD77 data files)
+        - **mgd77+** (for enhanced MGD77+ netCDF files)
+        - **gmt** (for old mgg supplement binary files)
+        - **xy** (for plain ASCII x, y tables)
+        - **xyz** (same, with one z-column)
+        - **geo** (for plain ASCII longitude, latitude files)
+        - **geoz** (same, with one z-column).
 
     suffix : str
         Specifies the file extension (suffix) for these data files. If not
         given we use the format definition file prefix as the suffix (see
-        *fmtfile*).
+        ``fmtfile``).
 
     discontinuity : str
         **d**\|\ **g**.
         Selects geographical coordinates. Append **d** for discontinuity at the
-        Dateline (makes longitude go from -180 to + 180) or **g** for
+        Dateline (makes longitude go from -180 to +180) or **g** for
         discontinuity at Greenwich (makes longitude go from 0 to 360
         [Default]). If not given we assume the data are Cartesian.
 
     spacing : str or list
          *dx*\[/*dy*].
-         *dx* [and optionally *dy*] is the grid spacing. Append **m** to
+         *dx* and optionally *dy* is the grid spacing. Append **m** to
          indicate minutes or **s** to indicate seconds for geographic data.
          These spacings refer to the binning used in the track bin-index data
          base.
 
     units : str or list
-        **d**\|\ **s**\
-        **c**\|\ **e**\|\ **f**\|\ **k**\|\ **m**\|\ **n**\|\ **u** .
+        **d**\|\ **s**\ *unit*.
         Sets the units used for distance and speed when requested by other
         programs. Append **d** for distance or **s** for speed, then give the
-        desired unit as:
+        desired *unit* as:
 
         - **c** - Cartesian userdist or userdist/usertime
         - **e** - meters or m/s
         - **f** - feet or feet/s
-        - **k** - km or kms/hr
+        - **k** - km or km/hr
         - **m** - miles or miles/hr
         - **n** - nautical miles or knots
         - **u** - survey feet or survey feet/s
 
-        Default is ``units=["dk", "se"]`` (km and m/s) if *discontinuity* is
-        set, and ``units=["dc", "sc"]`` otherwise (Cartesian units).
+        [Default is ``units=["dk", "se"]`` (km and m/s) if ``discontinuity`` is
+        set, and ``units=["dc", "sc"]`` otherwise (e.g., for Cartesian units)].
 
     {R}
     {V}
 
     gap : str or list
         **t**\|\ **d**\ *gap*.
         Give **t** or **d** and append the corresponding maximum time gap (in
-        user units; this is typically seconds [Infinity]), or distance (for
-        units, see ``units``) gap [Default is infinity]) allowed between the
-        two data points immediately on either side of a crossover. If these
-        limits are exceeded then a data gap is assumed and no COE will be
-        determined.
+        user units; this is typically seconds [Default is infinity]), or
+        distance (for units, see ``units``) gap [Default is infinity]) allowed
+        between the two data points immediately on either side of a crossover.
+        If these limits are exceeded then a data gap is assumed and no COE will
+        be determined.
 
     {j}
     """
@@ -182,13 +182,13 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs):
     r"""
     Calculate crossovers between track data files.
 
-    x2sys_cross is used to determine all intersections between ("external
-    cross-overs") or within ("internal cross-overs") tracks (Cartesian or
-    geographic), and report the time, position, distance along track, heading
-    and speed along each track segment, and the crossover error (COE) and mean
-    values for all observables. By default, x2sys_cross will look for both
-    external and internal COEs. As an option, you may choose to project all
-    data using one of the map-projections prior to calculating the COE.
+    Determines all intersections between ("external cross-overs") or within
+    ("internal cross-overs") tracks (Cartesian or geographic), and report the
+    time, position, distance along track, heading and speed along each track
+    segment, and the crossover error (COE) and mean values for all observables.
+    By default, :meth:`pygmt.x2sys_cross` will look for both external and
+    internal COEs. As an option, you may choose to project all data using one
+    of the map projections prior to calculating the COE.
 
     Full option list at :gmt-docs:`supplements/x2sys/x2sys_cross.html`
 
@@ -207,7 +207,7 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs):
         in the current directory and second in all directories listed in
         $X2SYS_HOME/TAG/TAG_paths.txt (if it exists). [If $X2SYS_HOME is not
         set it will default to $GMT_SHAREDIR/x2sys]. (Note: MGD77 files will
-        also be looked for via $MGD77_HOME/mgd77_paths.txt and \\*.gmt files
+        also be looked for via $MGD77_HOME/mgd77_paths.txt and .gmt files
         will be searched for via $GMT_SHAREDIR/mgg/gmtfile_paths).
 
     outfile : str
@@ -221,7 +221,8 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs):
     combitable : str
         Only process the pair-combinations found in the file *combitable*
         [Default process all possible combinations among the specified files].
-        The file *combitable* is created by *x2sys_get*'s -L option
+        The file *combitable* is created by :gmt-docs:`x2sys_get's -L option
+        <supplements/x2sys/x2sys_get.html#l>`.
 
     runtimes : bool or str
         Compute and append the processing run-time for each pair to the
@@ -230,15 +231,16 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs):
         is to use the knowledge of run-times to split the main process in a
         number of sub-processes that can each be launched in a different
         processor of your multi-core machine. See the MATLAB function
-        split_file4coes.m that lives in the x2sys supplement source code.
+        `split_file4coes.m
+        <https://github.com/GenericMappingTools/gmt/blob/master/src/x2sys/>`_.
 
     override : bool or str
         **S**\|\ **N**.
         Control how geographic coordinates are handled (Cartesian data are
         unaffected). By default, we determine if the data are closer to one
         pole than the other, and then we use a cylindrical polar conversion to
         avoid problems with longitude jumps. You can turn this off entirely
-        with *override* and then the calculations uses the original data (we
+        with ``override`` and then the calculations uses the original data (we
         have protections against longitude jumps). However, you can force the
         selection of the pole for the projection by appending **S** or **N**
         for the south or north pole, respectively. The conversion is used
@@ -267,10 +269,10 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs):
         not calculate a COE. Specify:
 
         - **l** sets lower speed [Default is 0].
-        - **u** sets upper speed [Default is Infinity].
-        - **h** does not limit the speed but sets a lower speed below which \
-        headings will not be computed (i.e., set to NaN) [Default calculates \
-        headings regardless of speed].
+        - **u** sets upper speed [Default is infinity].
+        - **h** does not limit the speed but sets a lower speed below which
+          headings will not be computed (i.e., set to NaN) [Default
+          calculates headings regardless of speed].
 
         For example, you can use ``speed=["l0", "u10", "h5"]`` to set a lower
         speed of 0, upper speed of 10, and disable heading calculations for
@@ -288,12 +290,14 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs):
 
     Returns
     -------
-    crossover_errors : pandas.DataFrame or None
+    crossover_errors : :class:`pandas.DataFrame` or None
         Table containing crossover error information.
-        Return type depends on whether the outfile parameter is set:
+        Return type depends on whether the ``outfile`` parameter is set:
 
-        - pandas.DataFrame table with (x, y, ..., etc) if outfile is not set
-        - None if outfile is set (track output will be stored in outfile)
+        - :class:`pandas.DataFrame` with (x, y, ..., etc) if ``outfile`` is not
+          set
+        - None if ``outfile`` is set (track output will be stored in the set in
+          ``outfile``)
     """
     with Session() as lib:
         file_contexts = []