DOCS: cleanup TOC and various docstring format issues #347
Conversation
There was a problem hiding this comment.
Thanks @davemfish ! Overall this looks great, but I was curious about reverting from f-string insertion of the warp algorithms back to statically defining the options.
| build: | ||
| os: ubuntu-22.04 | ||
| tools: | ||
| python: "mambaforge-22.9" |
| resample_method (string): the resampling technique, one of, | ||
| 'rms | mode | sum | q1 | near | q3 | average | cubicspline | | ||
| bilinear | max | med | min | cubic | lanczos' |
There was a problem hiding this comment.
Could you say more about this change?
My thinking behind making this an f-string was that different GDAL versions have different resample methods, and having a way to detect them programmatically and render them to a string for insertion into the docstring meant that we don't need to maintain it quite as much when these options change. Having said that, I don't think I verified that the strings would render in the API docs, so maybe this is the only way to have them display?
There was a problem hiding this comment.
So I changed it because sphinx was not rendering docstrings for these functions at all. It didn't raise any errors/warnings about it, but pydocstyle couldn't handle it either: PyCQA/pydocstyle#368
I didn't realize that different GDAL versions have different resample methods, though it makes sense. Unfortunately I don't think the variable in the f-string ever gets expanded, whether you're reading the docs on readthedocs, or in the source code, you never get to see the values.
Alternatively, we could just say, "must be one of the options supported by gdal.Warp", or something like that. What do you think? @phargogh
There was a problem hiding this comment.
Wow! That is both neat and highly unexpected. Sphinx must just be flexing/parsing (but not interpreting), and/or using an old version of the language. Either way, good to know!
So, for the current docstring, let's just leave it as-is. I have only ever seen gdal add resample methods (except for the one time they renamed 'nearest' to 'near'), so this is likely to be a subset in future releases.
Fixes #346
I'm interested in feedback & opinions about the table of contents before merging.
Edit: everybody was on board with the TOC change.
I also added some custom css to increase the font-size of the nested TOC items.