Documentation versioning

[cboulanger]

With the switch to sematic release, it becomes important to have a system that automatically creates documentation that reflects feature and breaking releases:

• No feature and breaking release should be done without a corresponding update and release of the documentation .
• qooxdoo.org/documentation should always have the latest version, qooxdoo.org/documentation/X.X the corresponding legacy docs.

[cboulanger]

Given that we switch to semantic release, we might also think about re-integrating the documentation into the main repo, which would solve many problems.

[oetiker]

yes :) hihi I think I mentioned that when the documentation was 'un-integrated' ... having the documentation with the code it documents makes things much simpler

[cboulanger]

@oetiker It had a lot to do with the fact that the Travis workflow and the review process were so inflexible so that the necessary wholesale revision of the documentation was made impossible or only only at glacial speed. Now that the revision has been done and we can use GitHub actions instead, it will be possible to have a much more granular review process, making the re-migration into the main repo possible. Plus the updates to the documentation will be much smaller and more seldom now.

[cboulanger]

Consensus is now to re-migrate the documentation into the main repository and use this repo to publish it in versioned form. This could be done by a repository_dispatch event fired when a breaking or feature release has been made.

[cboulanger]

What I intend to do next is to 1) merge the docs into qooxdoo/qooxdoo/docs 2) change the workflow in qooxdoo/documentation so that, when a tag is pushed on qooxdoo/qooxdoo, it is checked out and its docs folder is published at qooxdoo.org/documentation/<tag>.

This also means we can publish the docs folder in qooxdoo/qooxdoo at its GH pages (then accessible at https://qooxdoo.org/qooxdoo) - this would be the documentation of the current master state.

[cboulanger]

Checking markdown on documentation files works ✅

[cboulanger]

We now have a system in which, when you push a tag x to qooxdoo/qooxdoo master, https://qooxdoo.org/documentation/x will show the content of the "docs" folder of that tag.

This way, we have versioned documentation which does not burden the main repository.

Tags of the format "x.y.z" will be shortened to "x.y" so that a patch release will not generate its own documentation.