Update API documentation

[AbelVM]

Looks like the API documentation missed latest releases info, like:

• h3_to_center_child
• h3_get_pentagon_indexes
• h3_line
• h3index_hash
• All the functons here. It would be cool to add some explanation on the actual spatial meaning of index operators (=, >, <, <=, >=, &&, @>, <@) and the type of index they are supported by.

And some bonus points about indexing 😃

• Clarify what indexes, aside BTREE ( and R-tree through GiST?), are supported by h3index datatype.
• Does this PR mean that SP-GiST is nowadays supported? Or is it GiST?
• Specify whether the available indexes for h3index support clustering to improve spatial operations (and add this feature if the don't! 😝 )

[zachasme]

We are actually working on automatically generating API documentation on the auto-gen-docs branch, to avoid missing things like these in the future. 😃 I'll try and get the docs updated soon, but feel free to open a PR with the new docs (I mostly just copy from the h3 docs.

We haven't yet managed to get the GiST and SP-GiST indexes working properly. Any help is appreciated.

Good point on documenting supported indexes, that should definitely be in there.

I do not know whether the indexes support clustering. Have you tested it out? I'll have to do a bit of research on that.

[AbelVM]

I have found the operators info at https://github.com/bytesandbrains/h3-pg/blob/master/sql/install/00-type.sql but looks like the interesting ones are R-tree related, and looks like GiST is not available yet, so no use for these operators then 😞

Both B-tree and R-tree (with NOT NULL in the indexed column definition) indexes should support clustering.

Performing a clustering over an index that take into account spatial vicinity might improve later spatial quieries in several orders of magnitude. As per the 1st Law of Geography, most of the queries will read only a few pages from disk. Some benchmarks at the end of this page; the time improvements depends on the volume and how spatially scattered is the data

[zachasme]

The API reference is now automatically generated from the sql files, which means the operators, types and functions should now all be documented.

I've also added a test for clustering, which works as far as I can tell :-)