Add versioning for each doc item

[javiereguiluz]

Versioning is very important for Symfony Docs. Each doc page shows a version selector to read the same page for other Symfony versions. Most of the times this is trivial because the article maintains the slug/name and the path.

However, it's common to move contents in some versions. We have a file (https://github.com/symfony/symfony-docs/blob/master/_build/redirection_map) which maps old_path -> new_path ... so, for a given doc path, we can look up for the same path in older versions and if it doesn't exist, do a reverse lookup in that file to see if it had a different path in earlier versions.

Then, each doc item would include something like this:

"versions": {
  "2.0": "/something/foo",
  "2.1": "/something/foo",
  "2.2": "/something/foo",
  "...": "...",
  "2.7": "/new_something/foo",
  "2.8": "/new_something/foo",
  "...": "...",
  "4.0": "/new_something_new/bar",
  "4.1": "/new_something_new/bar",
  "master": "/new_something_new/bar",
}

This reverse lookup would be too expensive to do it when rendering the docs on the website, so it could be performed during the doc building process.

[weaverryan]

I like the idea - and the exact issue you’re targeting is annoying - I’ve hit it before. The issue is that the docs-builder is only ever aware of one “git repo” that its building at a time - it’s not aware internally of versioning. So... the docs-builder on its own couldn’t look at older versions to determine if a file is there or not.

Do you have any ideas or thoughts? We could do this (as an example) when 4.1 is being built, we can look in the redirect_map and determine all the “pages” that at some point redirected each current article path - eg that the current /bar was, at some point, called /foo and /baz (but we would not know which versions these were used on). That could then, in theory, be used on Symfony.com - maybe if the user visits a non-existent article on 4.0 called /bar, we redirect to /foo and if that’s a 404 again, we redirect to /baz. It seems a little complex... but ultimately this info needs to be compiled together on the server when all the docs are built together. But we can definitely dump easier-to-process metadata inside each build to help that.

[javiereguiluz]

After thinking about this ... I think it's better to move this into symfony.com itself. The build:docs command from symfony.com app knows when all versions have been built ... after that the command can process all versions at once to map all versions between them. Given that the generated contents are JSON files, it should be easy to parse them and update them with this new info.

[weaverryan]

Ok, perfect. Obviously, if there’s better output we can offer here, that’s an easy win :)