Ensure list of deprecated and experimental flags in docs remains in sync with deprecated / experimental status in code

Is your feature request related to a problem? Please describe.

From https://github.com/grafana/mimir/pull/5765#discussion_r1300813177

We mark configuration flags as deprecated and experimental in code (with the category:"experimental" tag), and maintain a list of deprecated and experimental features in the docs.

Nothing enforces that the list of deprecated and experimental flags in the docs are kept in sync, so it's very easy to forget to update the docs when changing the status of a flag in code.

Describe the solution you'd like

Either:

• a test or other check fails if the docs and code are out of sync
• the docs are autogenerated from the code (ie. marking a flag as deprecated in code automatically updates the docs to include that flag in the list of deprecated flags)

Describe alternatives you've considered

Continue manually maintaining this and continue forgetting to update the docs