docs: def do_flip(dec=None, inc=None, di_block=None):
      """
      This function returns the antipode (i.e. it flips) of directions.
  
      The function can take dec and inc as seperate lists if they are of equal
      length and explicitly specified or are the first two arguments. It will then
      return a list of flipped decs and a list of flipped incs. If a di_block (a
      nested list of [dec, inc, 1.0]) is specified then it is used and the function
      returns a di_block with the flipped directions.
  
      Parameters
      ----------
      dec: list of declinations
      inc: list of inclinations
  
      or
  
      di_block: a nested list of [dec, inc, 1.0]
  
      A di_block can be provided instead of dec, inc lists in which case it will
      be used. Either dec, inc lists or a di_block need to passed to the function.
  
      Returns
      ----------
      dec_flip, inc_flip : list of flipped declinations and inclinations
      or
      dflip : a nested list of [dec, inc, 1.0]
  
      Examples
      ----------
      Lists of declination and inclination can be flipped to their antipodes:
  
      >>> decs = [1.0, 358.0, 2.0]
      >>> incs = [10.0, 12.0, 8.0]
      >>> ipmag.do_flip(decs, incs)
      ([181.0, 178.0, 182.0], [-10.0, -12.0, -8.0])
  
      The function can also take a di_block and returns a flipped di_block:
  
      >>> directions = [[1.0,10.0],[358.0,12.0,],[2.0,8.0]]
      >>> ipmag.do_flip(di_block=directions)
      [[181.0, -10.0, 1.0], [178.0, -12.0, 1.0], [182.0, -8.0, 1.0]]
      """
      if di_block is None:
          dec_flip = []
          inc_flip = []
          for n in range(0, len(dec)):
              dec_flip.append((dec[n] - 180.) % 360.0)
              inc_flip.append(-inc[n])
          return dec_flip, inc_flip
      else:
          dflip = []
          for rec in di_block:
              d, i = (rec[0] - 180.) % 360., -rec[1]
              dflip.append([d, i, 1.0])
          return dflip