Create skeleton of documentation

[PoignardAzur]

This is a very messy, very basic skeleton of what Masonry documentation will eventually look like.

Main points are:

• Dedicated documentation modules.
• Re-using most of the language from the RFCs.

Next steps are:

• Flesh out the Widget documentation.
• Rewrite all those docs in a less placeholder-y way.
• Add chapter about the widget arena.
• Spread out that pass documentation to the respective pass files.
• Rewrite ARCHITECTURE.md.
• Add screenshots.

Fixes #376 and #389.

[PoignardAzur]

I'm marking this as ready for review despite the TODOs because I think this is a stark improvement over the previous state of our documentation.

The next be steps would be:

• Writing the "Testing widgets" chapters.
• Rewriting doc in the rest of the crate to reference this tutorial (and especially the "Concepts and definitions" chapter).

[Philipp-M]

Suggested change

	```ignore
	```rust,ignore

I'm not sure if the Github markdown renderer (or others) handles this better (i.e. syntax highlighting), but at least it has a chance to know that this is rust code.

(Same for the other ignore here)

I also wonder, if we should design these inline examples such that they compile, so that they're always in sync and checked via CI.
But I see this may increase the (not so interesting) code in these examples.
That could probably be avoided by # code that should not be rendered but that on the other hand has the disadvantage, to be shown in other markdown renderers (though I'd rather accept that TBH and be sure that everything is in sync).

[PoignardAzur]

I also wonder, if we should design these inline examples such that they compile, so that they're always in sync and checked via CI.

You're welcome to try. It's tough to do it in a way that doesn't make the examples tedious and unreadable. (Unless you use a lot of # marker to hide code from the reader.)

[DJMcNab]

This also interacts with #501. That is, we definitely should make these proper examples, but that work can reasonably be deferred.

Yes, that would involve using hidden harness code.

[DJMcNab]

I've scanned through the first three chapters. There are a few grammar issues, but overall this is looking really good.

I have also make a few UX suggestions. mostly for people who stumble upon this in GitHub

[DJMcNab]

Suggested change

	**TODO - Add screenshots - see [#501](https://github.com/linebender/xilem/issues/501)**
	<!-- TODO - Add screenshots - see [#501](https://github.com/linebender/xilem/issues/501) -->

[PoignardAzur]

I think I'll leave it as-is. I'd rather have a visible reminder.

[DJMcNab]

I'm surprised that this works - I thought it would be a coherence break

[PoignardAzur]

It doesn't work, hence the TODO comment. The final doc will use the free-function syntax.

[DJMcNab]

Looks good!

[runiq]

Below, you describe 'active text focus' and 'inactive text focus'. What's 'local text focus', though?

[PoignardAzur]

I think it's the same. Basically there's "the widget is focused, but the window isn't", and "the widget and the window are both focused". I need to take another crack at explaining this.

[DJMcNab]

Other than #632 (comment), I think this is ready to land.

I've not carefully re-reviewed since my last round, but overall it's better to get this in and allow updates to be collaborative.

[runiq]

This is a very welcome addition. I've been watching from the peanut gallery for the longest time, waiting for something like this. Thanks a lot for taking the time, I know how hard writing documentation is. <3

[PoignardAzur]

Thanks a lot for taking the time, I know how hard writing documentation is. <3

It's so much harder than it sounds.

You have to put your brain in a certain mode and pull things from it that it really doesn't want to give you by default.