ARTEMIS-5850 consolidate web console docs

[jbertram]

This commit combines the MarkDown-based documentation from the web site with the web console documentation from the main Artemis repo to create a consolidated set of documentation for the web console in AsciiDoc format.

As with the main Artemis documentation, this documentation will be copied to the website as part of the release process and will be versioned.

[gemmellr]

One of the main reasons the main artemis docs dont do 'latest' this way is that it means you cant test the site (assuming it will link to 'latest' since thats what we want people to use) without deploying it as the htaccess rules arent in force in the local Jekyll serve. (The artemis docs also dont use a symlink to similar effect, because the watcher cant discern this and then complains a lot about the duplicate-watching of the same files for changes). There is also the thing of it needing to be a 'temporary' redirect since it will be updated every release so browsers need to forget the redirect.

Another consequence of this approach is that you cant easily see the changes applied to the docs on the site between versions because the entire set is always new files. I think the history of change is useful, and have previously noticed unexpected issues from that. I think its a benefit worth retaining.

A middle ground rather than the htaccess magic would be to retain the actual-directory for 'latest' docs and update it as we go, but also create the versioned directory at the same time during release, rather than at the next release like with the main artemis docs. Though the downside of that is it means any post-release tweaks should be applied in 2 places. Probably not as much of a concern for the console as the broker etc as it changes less. Though that said, I do think we should make these changes post-release for 1.5.0 on the site.

[jbertram]

Regarding testing...Don't we have some kind of "staging branch" that will publish to a different sub-domain that we could use for this kind of testing? In any case, I think that once the .htaccess is known to work then we can trust that updating it appropriately won't break it.

That's a good point about the 301 vs 302 redirect. I'll fix that.

Regarding change history...Surely there's some git fu one could do to achieve some functional equivalence here. For what it's worth, I've never looked at the history for these files, although I often look at the history of the raw AsciiDoc files in the main artemis repo.

I originally considered having a copy in both 'latest' and '', but that violates my sensibilities. I really hope we can avoid this. I've updated the docs a number of times post-release and would like to avoid potentially having to do it in two places (although I agree this should be less likely with the console vs. the broker).

[gemmellr]

We do have staging. If left around when not using it, which seems to be the majority of the time (I dont recall anyone besides me really using it in over a decade on projects I've contributed to) then it sits stale most of the time unless cleared out. Things will inevitable start linking to it and get indexed if left around, which sucks if its stale. On the flip side its also a pain to use if cleaning it up after using it.

My issue is not with reliably updating the .htaccess (though it seems that was a problem this time), its the breaking of local development and not giving a choice but to deploy changes to test them, especially since the main link we would put on the download page etc then doesnt exist and would be a perpetual temp redirect. I dont think we should be breaking local development either way.

Now that I think about it, if the link always redirects, I think any indexing will likely always use the versioned dirs anyway. Little but our site will really reference the latest dir. Kinda seems like we might as well not have or use the 'latest' dir if doing it this way, and just update the sites console pages to always link to the newest version number.

I do look at the changes every time I update the site, or any repo really. I think everyone should be checking the diff, it often points to unexpected issues. E.g I found an entire copy of artemis release documentation in completely the wrong place recently, which probably wouldnt have happened if the diff had been looked at before pushing it. I dont know that you can actually git diff two different directories across two different revisions, which is what would be needed to similarly track changes vs a single directory with history. At the time of update yeah, you can regular-diff two distinct dirs.

[gemmellr]

I did think of an alternative that gives both a 'latest' dir and version-specific dirs the broker documentation can immediately reference...do the reverse of what this is currently doing. Use a stable 'latest' dir for the current docs, and redirect from <latest-version-number> --> latest. The 'add release script' then updates the redirect, and copies the old docs to the old version dir.