Allow browsing docs tagged for different versions. about docs HOT 12 CLOSED

This includes several tasks:

• include some button which allows us to switch the docs revision (read the docs has such)
• syncronize syncthing and syncthing docs git tags (I proposed including the docs source in the syncthing source, which would automatically fix the syncronization issue)
• adjust the release scripts to automatically tag the docs tree accordingly

from docs.

While we could include the docs in the main repo, it seems to me that we may not need to publish more detailed revisions than 0.11, 0.12, 0.13... That is, a tag or a branch per major version?

from docs.

From there it's no hassle to publish master at the root of the docs site, the v0.11 branch at /v0.11 and so on.

from docs.

I feel that 0.11, 0.12, 0.13 ... is enough. That could be solved by branch, you are right. But then may need to backport commits from master to, for example, 0.11. How do we want to deal with this? Maybe we could leave the docs as is and only backport major fails, e.g. wrong api endpoints in the api docs.

from docs.

There's a well defined point in the history where we updated the api docs and so on for v0.11, so we'd branch from there. I hope not too many people use that, so if there are some inconsistencies ... well, the interested parties can fix them after he fact. We do the same with v0.12 as we get to v0.13, so we'll have latest at / and then a branch for each previous release?

from docs.

I hope not too many people use that, so if there are some inconsistencies ... well, the interested parties can fix them after he fact.

Yeah, but once 1.0 has been released what update policy do we want to follow? Some lts like approach, or just keep rolling? I guess that e.g. the debian guys would somewhat freeze the version to one particular branch and backport bugfixes (when syncthing hits the official repos). If we keep some lts branch in the future, inconsistent docs should be avoided, shouldn't it?

from docs.

I think we should tag every release, even if nothing doc related has changed (essentially stacking up tags on a single commit). Even patch releases.

from docs.

If we were to go to that level, it sounds like it would make more sense to include it as a directory "docs" or so in the main repo?

from docs.

Or write some script to auto tag it when we tag the main repo.

The same thing could be said for discosrv, relaysrv and friends too...

from docs.

I've added tags here as a step one, by ways of this little script that copies tags from one repo to another based on the date the tag was created: https://gist.github.com/calmh/df20ffb54b2e7b5512de

This could be run periodically to push new tags as they pop up in the parent repo. It's not really the whole truth, as if we're actually maintaining two separate branches then we can't just base it on date.

from docs.

I just stumbled over this old issue.

• include some button which allows us to switch the docs revision (read the docs has such)

Seems mostly fixed by #721; details about the implementation at syncthing/syncthing#8107.

• syncronize syncthing and syncthing docs git tags (I proposed including the docs source in the syncthing source, which would automatically fix the syncronization issue)

Merging the repos is not done yet, obviously. Despite all benefits, I'm a little worried about all the automation stuff needing to be carried over. Each test build of the main repo will just take this much longer because all the docs need to be built (and deployed?) as well. Will it work seamlessly with Netlify? Will it work fine for pushing to the https://github.com/syncthing/docs-pre-rendered repo?

All these questions should be answered before we can make the merge.

• adjust the release scripts to automatically tag the docs tree accordingly

Does this happen automatically now? I thought it was pretty late in the v1.19.0 tag, but might be wrong.

Another great (and necessary) addition: Have a trigger on creating a new docs tag that will build it and upload to https://github.com/syncthing/docs-pre-rendered (build environment should be defined though). That didn't happen for the latest release, v1.19.0, yet.

It's a chicken-and-egg problem as well: Building https://github.com/syncthing/docs will clone https://github.com/syncthing/docs-pre-rendered, but the built version must be added there when finished, and added to versions.json. It's probably okay to postpone that until the next commit after a tag. @calmh do you have any solution in mind, as you already implemented the cloning of historic versions recently?

from docs.

All points above are addressed, except for the merger of docs and main syncthing repo. We don't need this issue to track that, hence closing.

from docs.