Improve Doc Function Reference categories

[mdavis]

This is a proposal to enhance the categorization of the PostGIS doc ​Function Reference page.

The current structure is getting a bit creaky, with categories having long lists of only vaguely related functions.

The proposed new categories are listed below. There are some notes about how the function links will be reorganized underneath them. Each category section will get a short introductory description summarizing the criteria for function inclusion. This is intended for user information and also to help guide where to add new functions.

This issue can capture discussion and design iteration if any. The actual doc change can be done once the design has settled.

1. Spatial Types
   • Renamed from PostgreSQL PostGIS Geometry / Geography / Box Types
2. Grand Unified Custom Variables (GUCs)
3. Version Functions
4. Table Definition Functions
5. Geometry Constructors
   • functions like MakeXXX
   • ST_LineFromMultiPoint, ST_Point
6. Geometry Accessors
   • Dump functions
   • ST_IsXXX
7. Geometry Validation
8. Geometry Editing
9. Transformations
   • Affine transformation functions
   • ST_Transform
   • ST_FlipCoordinates
10. BBOX Functions
    • Functions which return box types
    • ST_MakeBox2D, Box2D, etc
    • ST_EstimatedExtent
11. Geometry Input
    • functions to read from formats
12. Geometry Output
    • functions to write to formats
13. Operators - Spatial Relationship
14. Operators - Distance
15. Spatial Relationships
    • Binary predicates
    • ST_PointInsideCircle
16. Distance
17. Measurement
    • Length, area
18. Overlay
    • Union, Intersection, etc
    • Or title = Spatial Analysis ?
19. Geometry Processing
    • REMOVE - contents moved into other sections
20. Geometry Constructions
    • centroid, point-on-surface, boundary, boundingDiagonal, etc
    • Delaunay / Voronoi
21. Linear Referencing
22. Clustering
23. SFCGAL Functions
24. Trajectory Functions
    • Renamed from Temporal Support
25. Long Transaction Functions
26. Miscellaneous Functions
    • Try and assign all of these to other categories and REMOVE
27. Troubleshooting Functions
    • Renamed from Exceptional Functions

[dbaston]

Splitting the "processing" section makes sense to me.

I'd consider ordering the sections in order of most-used to least-used. We can only speculate about what that would be, but I'd think along the lines of:

• Spatial types
• Getting geometries in and out of PostGIS (Geometry Constructors / Geometry Input / Geometry Output)
• Spatial Relationships (predicates)
• Spatial Operations (overlays)
• Everything else

[komzpa]

robe2 can we get statistics from web server on accesses of functions once again? I believe last time we looked it made sense not to touch the table of contents as nobody looks there, instead concentrating on dbmanagement part of the doc which happened to be an unexpected for us entrypoint for most. we changed it in 2.5 and that might have shifted reading patterns. I hope ST_Intersects will be higher than ST_Contains this time.

mdavis can we go in smaller steps instead? "Let's move everything in draft and change in one go" is hard to understand. Can we do some obvious category one by one as a PR?

[mdavis]

dbaston: agreed, ordering by most-used makes sense. I did some of that, but also tried to avoid changing things around too much. Once the categories are built we can all have some fun arguing about the ordering

[mdavis]

komzpa: yes, can phase in the changes gradually via a series of PRs. Not sure I will know where to split things up though - do you have any suggestions?

[robe]

komzpa I believe you have ssh access to the server? and you did the stats last.

Also pramsey put in google analytics file on the doco a couple of months ago, so that might provide some good stats. I don't have access to postgis.net google analytics — he does.

[mdavis]

As suggested I have made a start with a small set of changes in ​this PR.

[komzpa]

In 17335:

Doc layout improvements.

Patch by Martin Davis.

References #4332
Closes ​https://github.com/postgis/postgis/pull/380

[komzpa]

A thing I once did was to group functions by how they convert the dimensionality. To me it makes sense as it gives hint that ST_Centroid can become ST_MinimumBoundingRadius which returns some other center which is not even obvious from the name.

[mdavis]

Replying to komzpa:

A thing I once did was to group functions by how they convert the dimensionality.

Great diagram! I agree, this is an interesting way to categorize spatial functions. Of course, it would be nice to be able to generate the lists automatically (similar to how the current Functions Index is produced). This would need an annotation in the docs to specify the dimensionality of the input & output. Which might be a nice thing to specify explicity anyway.

[mdavis]

Replying to komzpa:

it gives hint that ST_Centroid can become ST_MinimumBoundingRadius which returns some other center which is not even obvious from the name.

Perhaps ST_MinimumBoundingRadius should return a 2-point LineString, with the centre as the first point. That way the distance can be computed if needed, or the centre point extracted? And then the return type would be a line, which fits better with the term radius. (This is what JTS does).

Although I can see that in SQL perhaps having a composite type is convenient.

[mdavis]

I made some more progress on this proposal: ​https://github.com/postgis/postgis/pull/383

[komzpa]

In 17346:

Improve Doc Reference section

Patch by Martin Davis

Improve trajectory function section
Improve Long Transaction reference section
Add doc Reference Bounding Box functions section
Move doc Reference SFCGAL section
Move doc Reference Misc function Find_SRID
Move doc Ref ST_PointInsideCircle function
Move doc Ref ST_MemSize function
Move doc Ref function ST_Accum to Processing functions
Disable doc Ref Misc Functions section

References #4332
Closes ​https://github.com/postgis/postgis/pull/383

[mdavis]

Thanks @komzpa.

Will this change show up in ​https://postgis.net/docs/manual-dev/ at some point?

[komzpa]

As far as I understand this is some magic happening on Debbie's CI that robe knows how it works. Presumably it's a button to push somewhere in Jenkins.

[mdavis]

The docs are updated at that link, so the magic has happened.

[mdavis]

I have submitted another group of improvements in ​https://github.com/postgis/postgis/pull/385

[komzpa]

In 17361:

Improve Doc Reference section

Patch by Martin Davis

Reorganize functions into new sections:

Spatial Reference System Functions
Affine Transformations
Spatial Relationships
Measurement Functions
Clustering Functions

Also various wording improvements.

References #4332
Closes ​https://github.com/postgis/postgis/pull/385

[mdavis]

Added another PR for further improvements: ​https://github.com/postgis/postgis/pull/399

[mdavis]

In [17422]

Patch by mdavis

• Add sections Inputs
• Add subsections to Inputs, Outputs, Operators, Spatial Relationships
• Standardize Constructors and Accessors descriptions
• Various minor text changes/fixes

[komzpa]

Hello, is it implemented already or just partially?

[mdavis]

Mostly done…. but might revisit this once I am done current (non-doc) work.

[robe]

mdavis feel free to push this back to 3.0.0 if you have time to do it.