docs: def append_dist_to_shapes(feed: "Feed") -> "Feed":
      """
      Calculate and append the optional ``shape_dist_traveled`` field in
      ``feed.shapes`` in terms of the distance units ``feed.dist_units``.
      Return the resulting Feed.
  
      Notes
      -----
      - As a benchmark, using this function on `this Portland feed
        <https://transitfeeds.com/p/trimet/43/1400947517>`_
        produces a ``shape_dist_traveled`` column that differs by at most
        0.016 km in absolute value from of the original values
      - Assume the following feed attributes are not ``None``:
  
          * ``feed.shapes``
  
      """
      if feed.shapes is None:
          raise ValueError(
              "This function requires the feed to have a shapes.txt file"
          )
  
      feed = feed.copy()
      f = feed.shapes
      m_to_dist = hp.get_convert_dist("m", feed.dist_units)
  
      def compute_dist(group):
          # Compute the distances of the stops along this trip
          group = group.sort_values("shape_pt_sequence")
          shape = group["shape_id"].iat[0]
          if not isinstance(shape, str):
              group["shape_dist_traveled"] = np.nan
              return group
          points = [
              sg.Point(utm.from_latlon(lat, lon)[:2])
              for lon, lat in group[["shape_pt_lon", "shape_pt_lat"]].values
          ]
          p_prev = points[0]
          d = 0
          distances = [0]
          for p in points[1:]:
              d += p.distance(p_prev)
              distances.append(d)
              p_prev = p
          group["shape_dist_traveled"] = distances
          return group
  
      g = f.groupby("shape_id", group_keys=False).apply(compute_dist)
      # Convert from meters
      g["shape_dist_traveled"] = g["shape_dist_traveled"].map(m_to_dist)
  
      feed.shapes = g
      return feed