Update documentation and warnings before 0.1 release

[rhugonnet]

This PR improves the documentation in preparation for a first minor release 0.1! 🥳

The documentation now separates scientific background content and code examples, adds better links and plots to all feature pages, and adds some auxiliary pages for diverse uses based on user feedback (how to cite, method overview, cheatsheet for helping selecting a method, configuration, ecosystem, etc).

Link to rendered doc: https://xdem-rhugonnet.readthedocs.io/en/towards_0.1/index.html

Detailed documentation changes

This PR:

• Moves scientific background content that was mixed with the code examples, and adds new content, into a series of guides pages "Guides for elevated analysis" in the new section "Resources", illustrated with plots generated just for the documentation and a list for references for "More reading" at the bottom of the pages,
• Adds a "Cheatsheet: How to correct... ?" page in the new section "Resources" to help users read patterns of errors in elevation data to select a correction method,
• Adds an "Ecosystem" page in the new section "Resources" that points towards other relevant packages to pair with xDEM,
• Adds a "Citing and method overview" page in the section "Getting started", that points to xDEM's Zenodo and lists the references to use for all methods implemented in the packages,
• Adds a "Use in publication" page in the section "Reference", that lists scientific articles/theses that are using xDEM (to our knowledge),
• Adds a "Configuration" page in the section "Reference", that explains how to configure verbosity level, and georeferenced operations in xDEM via GeoUtils (resampling, etc),
• Streamlines and adds plots to the "Coregistration", "Bias correction" and "Uncertainty analysis" features pages for better understanding of these methods,
• Add "Quick use" subsections at the start of all feature pages, to save time for user who don't want to get into the details,
• Adds tables listing all methods at the start of "Terrain attributes", "Coregistration" and "Uncertainty analysis",
• Adds up-to-date descriptions of modular arguments and metadata for "Coregistration" based on recent changes,
• Adds equations used for "Terrain attributes",
• Adds more links to GeoUtils with explanation of the inheritance between packages,
• Adds links between feature pages and guide pages,
• Streamlines the API reference into a manually ordered list of submodule functions meant to be publicly referenced, and repeating functions that are from GeoUtils to facilitate user searches.

Other small changes

This PR also has some small changes in the core modules related to the documentation/visualization:

• Adds AffineCoreg.to_translations() and AffineCoreg.to_rotations() and AffineCoreg.from_rotations() (as from_translations() already existed) to quickly extract from/build the affine matrix, which might not be easy otherwise for a user (added in a note on the Coregistration page), which directly use pytransform3d (so don't require testing),
• Adds a resample option to apply_matrix for practicality (using a the subfunction _reproject_horizontal_shift_samecrs that was already tested, and is moved to the base module instead of affine),
• Adds more formatting options to Coreg.info() for types that were not yet supported (after some testing in the documentation), and a CoregPipeline.info() that simply wraps the Coreg.info() of each pipeline step,
• Updates the recent function DEM.estimate_uncertainty() to have clearer arguments, choice of method mirroring the new documentation.

TO-DO:

• Add profile curvature and plan curvature formulas on "Terrain attributes" page,
• Add BlockwiseCoreg to coregistration page,
• Add "Cheatsheet" page,
• Add link to PyTransform3d on Affine registration page,
• Add "Ecosystem" page,
• Add "Georeferencing intricacies" page,
• Add documentation for "DhMinimize" method,
• Streamline "Coregistration" and "Bias correction" pages,
• Detail .meta keys for users (and make the attribute public in a separate PR),
• Add .info() method for CoregPipeline,
• Remove temporarily BlockwiseCoreg,
• Update reference for TPI: Fix date in surface roughness reference #562,
• Re-structure/streamline "Spatial statistics for error analysis" guide page,
• Finalize "Uncertainty analysis" page, add warning that interface might change with Scikit-GStat now supporting directly sum of variogram models,
• Streamline "Differencing and volume change" into a "Gap-filling" page and add warning that it might be moved to a different package,
• Proof-read/streamline all gallery examples,
• Prepare banner to communicate breaking changes with 0.1,
• Check if figures in "Quick start" are fixed (normal colorbar, vector plotting on top),
• Check if PROJ error still appears or not in the rendered documentation, fix it if yes,
• Add "read more" section at the end of each guide page?
• Move down dDEM and DEMCollection in API, remove dDEM from README, and add warning of potential removal in future,
• Fix Nuth&Kääb gallery example colorbar title,
• Shorten detailed intros from gallery example,
• Fix all hyperlinks and warnings,
• Fix warnings of sphinx build,
• Release new GeoUtils with default tight layout,
• Fix cheatsheet vertical CRS failing to download on RTD, Opened Vertical CRS download fails on "Cheatsheet" documentation page #646
• Fix bias-correction sinusoid example sometimes failing to correct randomly. Couldn't! Opened Find out why DirectionalBias correction for sum of sinusoids randomly fails #637

Resolves #477 (last step)
Resolves #505
Resolves #464
Resolves #434
Resolves #285
Resolves #275
Resolves #431
Resolves #532
Resolves #528
Resolves #562
Resolves #583
Resolves #614

Opens #637
Opens #638

[rhugonnet]

Accounted for all comments, opened issues otherwise. All tests passing.
Merging!

[vschaffn]

@rhugonnet It's probably not deliberate, but the logging.md doc has been removed from your updates, and the logging_configuration.py example has been renamed plot_logging_configuration.py

[rhugonnet]

@vschaffn This is intended, I tagged you a couple weeks ago to explain these changes: #502 (comment) 😉
Feel free to comment a posteriori in #640

[rhugonnet]

In short: None of the two pages were rendering after #610. For instance, renaming into "plot_xxx" is required for it to be rendered by Sphinx-Gallery, otherwise it is shown without execution of the code.
In the comment above I explain how you can check the documentation rendering in the future with your own RTD fork setup 🙂

[vschaffn]

@rhugonnet Sorry, I had forgotten about that comment, thanks for the reminder 😃