Docs reimagining

[ktoso]

Disclosure, this is a very large refactoring and AI assistance was used to make the content consistent and add all the snippet markers. I've reviewed this deeply, iterated multiple times and made sure all the prose is human written and/or adjusted, we don't want just plain ai generated docs especially in prose, but automating all the "snippets" finding and adjustment was a huge help from ai tools.

--

This does a few things:

• we change the organization of docs to be about features and tools
• we use code snippets form tests to showcase each feature
• we automate the generation of swift-java.config docs and validate it upon CI runs.

This does a few hacks since docc doesn't allow linking snippets from "other places" and they must be in Snippets/ but we do not want them there, we want them to be validated with tests in normal sample apps like today. So This does a symlinking trick to keep them accessible to docc, but keep them in the right places. This breaks syntax highlighting on them... I'm looking for solutions to this.

This also uses the fact that we now support non-Swift snippets, which I've contributed over here: swiftlang/swift-docc-plugin#120

We'll need to work more with docc to meet our requirements here, but this is already a huge improvement.

I'll be going over all the examples to make sure they all make sense and are complete etc.

---

The docs are MUCH improved with this and this is how it looks like:

[ktoso]

I'm sure I left some mistake somewhere still, but this is a huge improvement and I'd like to keep working in this new world of docs for us :-)