Documentation should be versioned, with versions matching each released project tag

[Ocramius]

Moved from doctrine/orm#6060

[yannickl88]

I've been trying to make sense of the docs and this project but there seems to be a lot of broken links and broken features.

Some examples being:

• Search
• Version switching feature
• MongoDB Abstraction Layer documentation
• Annotations documentation
• Collections documentation
• and more...

Are you planning on continuing to use this system? Would you be open to try something different (or something custom)?

I might have some free time to mess around to see if I can come up with a better alternative if you would be open to the idea. I think it would greatly benefit the project to have documentation on-par with the likes of Symfony.

[Ocramius]

I've been trying to make sense of the docs and this project but there seems to be a lot of broken links and broken features.

We did:

• split the projects
• re-merge docs into the single projects

And that likely broke existing features of the docs.

Are you planning on continuing to use this system?

Yes

Would you be open to try something different (or something custom)?

No, not worth it - this just needs work that nobody currently has time to do.

I might have some free time to mess around to see if I can come up with a better alternative

Please don't look for alternatives: this just needs a good amount of cleaning and build script fiddling.

I think it would greatly benefit the project to have documentation on-par with the likes of Symfony.

Yes, but we don't have the time to get there, sorry.

[yannickl88]

Ah, that might explain it yes. Okay fair enough. Is there anything I could help out with at this time?

[Ocramius]

@yannickl88 sure! This entire thing is just a set of build scripts that compile to HTML, so if we respect RST semantics, relative links should "just work".

I think this issue in particular is a good start, or else we can settle with only providing "latest" documentation, whereas "current" documentation is still available in the checked out docs/ dir in vendor, once the project is installed locally. Tradeoffs, but we need to see if there are any huge advantages to providing both.

Another solution is to provide the current branch/hash as part of the deployed documentation somewhere.