search

doctrine / doctrine-website-sphinx

Sphinx-based Doctrine Website
18 stars 25 forks source link

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

Open Ocramius opened 7 years ago

Ocramius commented 7 years ago

Moved from https://github.com/doctrine/doctrine2/issues/6060

yannickl88 commented 7 years ago

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:

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 commented 7 years ago

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:

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 commented 7 years ago

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

Ocramius commented 7 years ago

@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.