Documentation revision

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

[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.

[StevenLi-DS]

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