📚 ci: automate docs deploy + releases; fix dead badges/links

[PavelGuzenfeld]

Problem

Two things broke around the v1.2.0 release:

1. The website (https://boost-ext.github.io/sml/) didn't update. It is served from the gh-pages branch (Pages legacy mode), but no workflow regenerates it — the only workflow is build (compile + test). gh-pages has been frozen since 2022-09-07, so doc changes on master never reach the live site.
2. No v1.2.0 Release/tag exists. Merging the release PR only bumped BOOST_SML_VERSION in source. The latest published Release/tag is still v1.1.13 even though master is 1.2.0 — tagging + releasing was a manual step that was never automated.

While here, several badges/links on the site were dead: the Travis badge (Travis CI shut down for OSS) and the AppVeyor badge both 404, and doc/overview.md linked compilers to travis-ci.org/appveyor.

What this PR does

Automation (the actual fix):

• ​.github/workflows/docs.yml — builds the MkDocs site and publishes it to gh-pages whenever docs change on master (or via manual dispatch). keep_files: true preserves the /boost classic mirror and conference slides.
• ​.github/workflows/release.yml — manual dispatch that derives the version from BOOST_SML_VERSION, creates the vX.Y.Z tag and a GitHub Release from the matching doc/CHANGELOG.md section. Idempotent — a no-op if the release already exists.

Modernization & content:

• ​.mkdocs.yml — builds on current MkDocs 1.6 / Python 3.12 (verified). Drops the !!python/object/apply:os.getenv custom_dir hack and the dead Universal Analytics property (UA-…, sunset by Google in 2023). Output is byte-for-structure identical to the legacy build.
• doc/index.md, doc/overview.md — replace dead Travis/AppVeyor badges and compiler links with the GitHub Actions equivalents; switch the version badge to shields.io/github/v/release.
• Makefile — restore make doc / make serve (the doc targets were dropped when the Makefile was slimmed to a CMake wrapper).

The acknowledgements credit is a separate commit so it can be taken or dropped independently of the infra fixes.

Verification

Built locally with MkDocs 1.6.1 on Python 3.12 — clean build, all pages render, badges/credit present. Remaining badges fetched live: build = passing, issues = 143 open, codecov = 100%, version = v1.1.13 (will flip to v1.2.0 once the release workflow runs).

⚠️ Maintainer actions required

1. Repo setting: Settings → Actions → General → Workflow permissions must allow Read and write (the workflows request contents: write, but the org/repo default can cap it). Without this both workflows fail to push.
2. Merging this PR auto-deploys the site — the merge commit touches doc/** + .mkdocs.yml, so docs.yml runs on the push and updates gh-pages (commit by github-actions[bot]). Expected, not a surprise.
3. To cut v1.2.0: run the release workflow once (Actions → release → Run workflow). It tags v1.2.0 and publishes the Release from the CHANGELOG.

Note

codecov renders 100% but its data is frozen at the last Travis-era upload — build_matrix.yml has no coverage step. Left as-is (README keeps it too); worth either adding a coverage upload or dropping the badge in a follow-up.

---

Update — documentation overhaul (additional commits)

Following review of the live site, this PR now also fixes the broken doc content and pages:

Broken links / 404s (index.md)

• The Changelog / Tutorial / Examples buttons and the "Try it online" link pointed at <page>/index.html, which 404 under use_directory_urls: false. Repointed to the flat CHANGELOG.html / tutorial.html / examples.html (+ fixed the hsttp:// typo). Verified against the built tree (examples.html#hello-world anchor exists).

"Run" buttons → Compiler Explorer

• Removed the broken ![CPP(BTN)](Run_*) buttons (39 across index/tutorial/user_guide). Each was already paired with a working ▶ Run on Compiler Explorer link, so only the dead button is dropped.
• Compiler Explorer links now open in a new browser tab (utility.js).

New examples (present in example/ but undocumented), each with a verified CE link:

• Eval, Visitor, Dispatch Policy.

FAQ — added from open issues (answers grounded in the User Guide API table / v1.2.0 CHANGELOG):

• How to get/inspect current state(s) — How to get current states in action/entry? #476
• Check if in one of several states — [question] Possibility to check if I am in one of several states without releasing mutex in between #632
• Event instance / handled return value of process_event — Using event instance with process_event() #487
• Async dispatch via flush_queue() — Dispatching events in separate thread spawned from action? #583
• Discard deferred events via clear_defer — Access to defer_queue #643
• Is SML part of Boost? — When is SML officially part of Boost? #511
• Moore vs Mealy — Question: Moore or Mealy state machine? #575

I left review comments on each of those issues pointing at the answer. Drop any FAQ entry you'd rather not keep.

[kris-jusiak]

All required permission should be there

[kris-jusiak]

https://github.com/boost-ext/sml/releases/tag/v1.2.0