Opened 5 years ago
Last modified 3 years ago
#4332 assigned enhancement
Improve Doc Function Reference categories
| Reported by: | mdavis | Owned by: | mdavis |
|---|---|---|---|
| Priority: | medium | Milestone: | PostGIS Fund Me |
| Component: | documentation | Version: | master |
| Keywords: | Cc: |
Description
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.
- Spatial Types
- Renamed from PostgreSQL PostGIS Geometry / Geography / Box Types
- Grand Unified Custom Variables (GUCs)
- Version Functions
- Table Definition Functions
- Geometry Constructors
- functions like MakeXXX
- ST_LineFromMultiPoint, ST_Point
- Geometry Accessors
- Dump functions
- ST_IsXXX
- Geometry Validation
- Geometry Editing
- Transformations
- Affine transformation functions
- ST_Transform
- ST_FlipCoordinates
- BBOX Functions
- Functions which return box types
- ST_MakeBox2D, Box2D, etc
- ST_EstimatedExtent
- Geometry Input
- functions to read from formats
- Geometry Output
- functions to write to formats
- Operators - Spatial Relationship
- Operators - Distance
- Spatial Relationships
- Binary predicates
- ST_PointInsideCircle
- Distance
- Measurement
- Length, area
- Overlay
- Union, Intersection, etc
- Or title = Spatial Analysis ?
Geometry Processing- REMOVE - contents moved into other sections
- Geometry Constructions
- centroid, point-on-surface, boundary, boundingDiagonal, etc
- Delaunay / Voronoi
- Linear Referencing
- Clustering
- SFCGAL Functions
- Trajectory Functions
- Renamed from Temporal Support
- Long Transaction Functions
Miscellaneous Functions- Try and assign all of these to other categories and REMOVE
- Troubleshooting Functions
- Renamed from Exceptional Functions
Change History (24)
comment:1 by , 5 years ago
comment:2 by , 5 years ago
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?
comment:3 by , 5 years ago
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 
comment:4 by , 5 years ago
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?
comment:5 by , 5 years ago
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.
comment:6 by , 5 years ago
As suggested I have made a start with a small set of changes in this PR.
follow-ups: 9 10 comment:8 by , 5 years ago
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.
comment:9 by , 5 years ago
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.
comment:10 by , 5 years ago
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.
comment:11 by , 5 years ago
I made some more progress on this proposal: https://github.com/postgis/postgis/pull/383
comment:13 by , 5 years ago
Thanks @komzpa.
Will this change show up in https://postgis.net/docs/manual-dev/ at some point?
comment:14 by , 5 years ago
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.
comment:16 by , 5 years ago
I have submitted another group of improvements in https://github.com/postgis/postgis/pull/385
comment:18 by , 5 years ago
| Owner: | changed from to |
|---|---|
| Status: | new → assigned |
comment:19 by , 5 years ago
Added another PR for further improvements: https://github.com/postgis/postgis/pull/399
comment:20 by , 5 years ago
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
comment:22 by , 5 years ago
Mostly done…. but might revisit this once I am done current (non-doc) work.
comment:23 by , 5 years ago
| Milestone: | PostGIS 3.0.0 → PostGIS 3.1.0 |
|---|
mdavis feel free to push this back to 3.0.0 if you have time to do it.
comment:24 by , 3 years ago
| Milestone: | PostGIS 3.1.0 → PostGIS Fund Me |
|---|
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: