Feat: hosts can configure deprecation details

[nhoening]

Description

We fix the deprecation and sunset dates which are sent in headers to users.
Hosts should be able to communicate the dates (and info URLs) which they will actually use for deployments of new FlexMeasures versions.

• introduce FLEXMEASURES_DEPRECATION_AND_SUNSET so hosts can customize when they deprecate and sunset
• docs: re-organize config settings into more fitting sections
• Added changelog item in documentation/changelog.rst

Read the new tests, and re-generate sphinx docs (or look at the RTD build) and read the configurations.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #34433555 | 📁 Comparing 3b1ade0 against latest (a3fb811)

  🔍 Preview build  

132 files changed · + 19 added · ± 113 modified

+ Added

• _autodoc/COUPLING.html
• _autodoc/COUPLING_COEFFICIENT.html
• _autodoc/INFLEXIBLE_CONSUMPTION.html
• _autodoc/INFLEXIBLE_PRODUCTION.html
• _autosummary/flexmeasures.api.common.rate_limiting.html
• _autosummary/flexmeasures.api.v3_0.utils.html
• _autosummary/flexmeasures.data.models.automations.html
• _autosummary/flexmeasures.data.models.planning.highspy_optimization.html
• _autosummary/flexmeasures.data.models.planning.scheduling_problem.html
• _autosummary/flexmeasures.data.schemas.automations.html
• and 9 more...

± Modified

• changelog.html
• configuration.html
• genindex.html
• getting-started.html
• http-routingtable.html
• index.html
• py-modindex.html
• _autodoc/CONSUMPTION_CAPACITY.html
• _autodoc/GROUP.html
• _autodoc/INFLEXIBLE_DEVICE_SENSORS.html
• and 103 more...

[Flix6x]

It seems as if the real feature of this PR is not to let hosts configure deprecation details (they could already), but to let the override tackle multiple versions with different details rather than just one version.

Although I consider it likely that only a single deprecation&sunset campaign would be active for the FM API at any given time, I'd happily accept this as an improvement. I only suggest a simplification in the way API versions are formatted.

Let me follow up on this myself and do one more test.

[Flix6x]

Thanks — I've pushed my own suggestions in 3b1ade0, so approving.

One bug worth flagging, which predates my review: the key list in configuration.rst documented api-v1, but that key never matched anything. The lookup key is derived from api_version_being_sunset, which is "1.0" for the v1 blueprint (that's also what produces the "API version 1.0 has been sunset" message), not from the /api/v1 URL prefix. So under the original formula it should have read api-v1_0, and under the new dotted one api-v1.0. I verified both locally:

OLD code (api-v{version.replace('.','_')}), against /api/v1:
  api-v1   -> miss     api-v1_0 -> HIT     api-v1.0 -> miss

NEW code (api-v{version}), against /api/v1:
  api-v1   -> miss     api-v1_0 -> miss    api-v1.0 -> HIT

The other four entries were fine. Docs now list api-v1.0 … api-v2.0.

Note this leaves the config keys deliberately keyed on the API version rather than the URL segment (/api/v1, /api/v1_1, /api/v2_0). I think that's the right call, but if you'd rather have them mirror the URLs, the cleanest route is setting the first entry's api_version_being_sunset to "1" — that also changes the 410 message, so I left it alone.

I also added test_sunset_falls_back_to_built_in_info, which asserts that with no host override the sunset v1, v1.3 and v2.0 blueprints still return the SUNSET_INFO dates and links (Deprecation/Sunset headers, both Link headers, and the sunset link in the 410 body).