In docs, make use of version_added, version_changed, deprecated etc sphinx directives

[phlax]

description

if we included in the documentation the version information - ie when added, changed, deprecated or removed it would be very helpful for users.

it would also might make it clearer why problems coming from version/configuration mis/matches do/not work

i think we can get most of this information from protos - not sure immediately how we show removed - but that would be v helpful when upgrading

[phlax]

sphinx docs are here https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded

[phlax]

related (deprecation) pr - #15564

[daixiang0]

@phlax hi, I would like to do it, where can I start first?

[phlax]

@daixiang0 that would be amazing

there are quite a few parts to this so its probably not trivial - lets focus on #16093 first - and we can look at this after

[daixiang0]

Could you share more details here?

[phlax]

broadly we need to figure out:

1. where to store this information
2. where to render the information
3. a strategy for when to use these

and maybe a few other things.

im thinking we probably want to store this information in the protos with annotations.

the question of where to render is more complex than it might first seem as so much of Envoy config is implemented through extensions

in terms of a strategy, my feeling is to focus on one or two known api changes initially and then expand to others with lessons learnt

my suggestion for an initial focus would be the changes to admin/access_log in the recent version

[phlax]

for reference on how other projects use these (not necessarily in relation to config) the django docs guidelines are worth checking out:

https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/#documenting-new-features

[phlax]

@daixiang0 can you join the Envoy slack - there is a doc-improvements channel which it might be helpful to discuss on

[daixiang0]

Yep, I am in the slack now.

[phlax]

im unable to find you there by your username - can you join #doc-improvements

[daixiang0]

I ping you directly in slack :)