Improve docstring of x2sys_init and x2sys_cross

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 mapprojections 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 = []