API Docs are not well formatted for Args docstring.
bw4sz opened this issue · comments
While working on another issue I can see that we have issues with the API formatting docs.
Example of a well formatted API reference.
![image](https://private-user-images.githubusercontent.com/1208492/340406121-74e2d95b-a805-4f94-b6bd-a807cf8362bd.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjQ3MTM0OTUsIm5iZiI6MTcyNDcxMzE5NSwicGF0aCI6Ii8xMjA4NDkyLzM0MDQwNjEyMS03NGUyZDk1Yi1hODA1LTRmOTQtYjZiZC1hODA3Y2Y4MzYyYmQucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDgyNiUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA4MjZUMjI1OTU1WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ZTQ4OTkxZjJlY2VjNjc3Mjk5N2QxOWIzYzkwMGI0YmU2ODcwZDFlOTNiMzA0MDk2ZjM3NjY2ZDlmMGZjNjBmZCZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.f4wzu32pgai8Nlyd2VgeQ73RtYUH2nFFAdlMx6PIexY)
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.
![image](https://private-user-images.githubusercontent.com/1208492/340406313-ac910f3c-5900-490b-82c7-29a49c941166.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjQ3MTM0OTUsIm5iZiI6MTcyNDcxMzE5NSwicGF0aCI6Ii8xMjA4NDkyLzM0MDQwNjMxMy1hYzkxMGYzYy01OTAwLTQ5MGItODJjNy0yOWE0OWM5NDExNjYucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDgyNiUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA4MjZUMjI1OTU1WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ODMxZjM5YWM0MWE4Y2UzNmIxODY5OTI5Mzc3NzllZjliMjZkZmNkMmJmN2ExZWZkODE5YTIyZDdjY2M0ZGQwMiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.g02JxAMqs4wzYsCNTrMswwbQOSWV9meUq7XVkkIyVKg)
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.
- Regenerate documentation locally (https://deepforest.readthedocs.io/en/latest/CONTRIBUTING.html#documentation) and make sure the bullets appear, there is an Args and Returns statement. I know some docstrings need to be updated, leave that for now.