Documentation revision

[martinfleis]

I feel that documentation of GeoPandas needs some love. I am pretty happy with our user guide - it is extensive, nicely done, easy to understand. However, there are two issues I see at the moment.

1. Examples

There is an old issue #280 discussing this. Our example gallery is handled by sphinx-gallery, but it does not work for Jupyter notebooks. As we have currently more notebooks than .py files in examples, this does not really work and we need to figure out how to make them visible.

2. Reference guide

Reference guide is one big mess. As much as I like shapely's docs, which are on one page, I dislike the way we have it. The structure which is there is only very rough, it is hard to navigate in it, not mentioning large part of functions which are not included (#1052). I am not aware of existing discussion on this topic, so it might not bother many people, but I rather search in GitHub repo for docstrings than in docs reference guide.

My ideas on these are below.

Examples - I would dump sphinx-gallery in favour of nbsphinx and convert our .py examples to notebooks. See the docs. But it might be better to keep this discussion in #280.

Reference guide - this is more complicated, but we should introduce more structured approach as capabilities of geopandas are widening. I really like the way pysal is handling their API documentation. From the first sight it is clear what are the options, where I will find more details, I know what is going on. So instead of having everything at the same page, I would split it into similar structure where details would show only if you want them. Have a nice list of methods and functions, with short description and details (ideally including short examples of usage) move to separate pages. All of it can be done with sphinx, not special tools are needed.

I want to open discussion on this. @StevenLi-DS already mentioned that he has some ideas - bring them on.

cc @geopandas/collaborators

[stevenlis]

• As mentioned in https://github.com/geopandas/geopandas/issues/991 and https://github.com/geopandas/geopandas/issues/1052, some methods and functions have been missing from the reference page: explode, collect, points_from_xy, and dissolve.

• At the bottom of the page, it might be more clear to call it "Top-level Functions" than "API Pages".

• It might be helpful to add a note to explain the appropriate geometries (e.g., points, polygons) a user should apply a method to. For example, for GeoSeries.contains(), since only a polygon can contain other objects, maybe the doc should have a note for it. Meanwhile, it has a parameter call other:GeoSeries or geometric object, which might be better to specify the geometric object as points or polygons like: other:GeoSeries or geometric object (i.e., points or polygons). or maybe even a chart to list all the methods and attributes

Methods/Attributes	Can be applied to	Can be used as a parameter
contains()	polygons	polygons, points
within()	points, polygons	polygons
representative_point()	polygons	N/A
distance()	points, polygons(centroids)	points, polygons(centroids)
crosses()	polygons	polygons
area	polygons	N/A
bounds	polygons	N/A

• add a space around the : between each parameter and dtypes for readability. For example: other : GeoSeries or geometric object

• It is not very clear that what the "Geoseries (elementwise) " means.

[stevenlis]

@martinfleis

I really like the way pysal is handling their API documentation.

I also like it, which looks like very much like seaborn's doc as well. It could also allow folks to add more plots to explain the methods since it's very hard to make sense of any geometric operations without visualizations.

[magtanggol03]

@martinfleis @StevenLi-DS Hi!

I love geopandas, but I'm very new to open source. Would love to help out improving the documentation of geopandas but not sure where to start.

Is there anything I can do to start?

Thanks and love the work you guys are doing!

[martinfleis]

@magtanggol03 Hi, happy to hear that!

You can try to update contextily example (#1077) or add a detailed docstring to points_from_xy (#991). Or generally look for issues with documentation label. A bit more details are in our contributing guidelines. This issue is more a discussion at the moment. If you'll need details how to do some PR, you can ask in a relevant issue. Thanks!

[stevenlis]

Am I missing something? We don't actaully have a chagnelog in the doc?

[martinfleis]

@StevenLi-DS apparently we have one only in the root as .md. I'll open a new issue for that. That could be resolved separately without revising the rest of the documentation.