While working on another issue I can see that we have issues with the API formatting docs.
Example of a well formatted API reference.
def shapefile_to_annotations(shapefile,
rgb,
buffer_size=0.5,
geometry_type="bbox",
savedir="."):
"""
Convert a shapefile of annotations into annotations csv file for DeepForest training and evaluation
Geometry Handling:
The geometry_type is the form of the objects in the given shapefile. It can be "bbox" or "point".
If geometry_type is set to "bbox" (default) then the bounding boxes in the shapefile will be used as is and transferred over
to the annotations file. If the geometry_type is "point" then a bounding box will be created for each
point that is centered on the point location and has an apothem equal to buffer_size, resulting in a bounding box with dimensions of 2
times the value of buffer_size.
Args:
shapefile: Path to a shapefile on disk. If a label column is present, it will be used, else all labels are assumed to be "Tree"
rgb: Path to the RGB image on disk
savedir: Directory to save csv files
buffer_size: size of point to box expansion in map units of the target object, meters for projected data, pixels for unprojected data. The buffer_size is added to each side of the x,y point to create the box.
geometry_type: Specifies the spatial representation used in the shapefile; can be "bbox" or "point"
Returns:
results: a pandas dataframe
"""
Example of a poorly formatted API reference.
def view_dataset(ds, savedir=None, color=None, thickness=1):
"""Plot annotations on images for debugging purposes
Args:
ds: a deepforest pytorch dataset, see deepforest.dataset or deepforest.load_dataset() to start from a csv file
savedir: optional path to save figures. If none (default) images will be interactively plotted
color: color of the bounding box as a tuple of BGR color, e.g. orange annotations is (0, 165, 255)
thickness: thickness of the rectangle border line in px
"""
Missing the bullets and subheadings
I think this is because we lack a carriage return before Args, not 100% sure.
Next steps
[ ] confirm how fix the formatting guidelines
[ ] go through docstrings and make sure there are carriage returns (if thats it) before all Args in docstrings.
While working on another issue I can see that we have issues with the API formatting docs.
Example of a well formatted API reference.
Example of a poorly formatted API reference.
Missing the bullets and subheadings
I think this is because we lack a carriage return before Args, not 100% sure.
Next steps